Welcome to Natural’s documentation!

Natural is a Python library to easily transform data into human-readable formats such as dates, time differences, numbers and sizes.


  • Natural is not using any third-party libraries, so it runs from a bare Python installation
  • Natural is fully internationalised and speaks your language
  • Natural uses unicode strings where possible
  • Natural is PEP8 compliant
  • Natural has an extensive test suite


>>> from natural import date, number, size
>>> import datetime
>>> date.compress(datetime.datetime(2012, 01, 01, 23, 42))
>>> number.word(2300000)
'2.3 million'
>>> size.filesize(102410241024)
'95.377 GB'

We speak your language too!

>>> import locale
>>> locale.setlocale(locale.LC_ALL, 'de_DE')
>>> from natural import date
>>> date.duration(1337000000)   
'vor 4 Wochen'

Indices and tables