Skip to content
Find currencies / money talk in natural text
HTML Python
Branch: master
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Type Name Latest commit message Commit time
Failed to load latest commit information.


Build Status PyPI PyPI

natura: pun based on "paying in natura" and detecting money in natural language.

Find and convert money amounts in text.

from natura import Finder
mf = Finder()
mf.findall("500 EUR $500 and five hundred yen")
# [Money(value=500.0, currency='EUR', matches=['500', 'EUR'], base_amount=500.0, base='EUR', ...),
#  Money(value=500.0, currency='USD', matches=['$', '500'], base_amount=441.462, base='EUR', ...)
#  Money(value=500.0, currency='JPY', matches=['five', 'hundred', 'yen'], base_amount=4.404, ...)]

Takes clues to solve ambiguity:

mf.find("In Australia, 500 dollars recently became worth less")
# Money(value=500.0, currency='AUD', matches=['Australia', '500', 'dollars'], base='EUR', base_amount=336.089, ...)

Have access to the spans of the matches:

res = mf.find("In Australia, 500 dollars recently became worth less")
# [(3, 12), (14, 17), (18, 25)]

for example, for display:

In Australia, 500 dollars recently became worth less


Tested for 2.7 and 3.5:

pip install natura


  • base_currency: can be changed using Finder(base_currency="USD")

  • conversion_backend: can use different websites as backends: Finder(converter=MyClass)

    Note: Default, no converter is used. To use converter, create an account and request a key.

    from natura.conversion_backends import FixerIOExchangeRate
  • locale: create your own locales with different behavior

  • thread-safe caching: can implement different caching schedule: Finder(converter=MyClass)

    • Currently implements hourly updates and stores locally in sqlite3
  • ignore_conversions: Finder(converter=None)

  • numeric_to_money: Force numbers to become money if you know there has to be money mentioned:

Bot: "How much local money would you like to spend?"

Answer: "I would not spend more than 500"

mf.find("I would not spend more than 500", numeric_to_money=True)
# Money(value=500.0, currency='EUR', spans=[(28, 31)], matches=['500'], base='EUR', ...)
  • accurate: no false hits:
mf.find("I want to buy 500 apples.")
# None


Yes please. There are multiple ways you could help:

  1. Implement new functionality, pull requests are very welcome
  2. Create a new locale for your language
  3. Identify cases that don't work and you think should work, pick one:
    1. Make an issue describing what doesn't work
    2. Make a pull request with an newly added test that does not pass
    3. Make a pull request with a newly added test including a FIX :)
You can’t perform that action at this time.