# nombres_vers_lettres
A Python package to write numbers in French, with a simple script. The reason I made this package is the complexity of this simple task that often lead the implementation of such a tool to produce erroneous results (see [this issue](https://github.com/savoirfairelinux/num2words/issues/532)).
## Installation
You can easily install this package using `pip`.
```bash
python -m pip install nombres_vers_lettres
```
Or for the development version:
```bash
python -m pip install git+https://github.com/Vincent-Stragier/nombres_vers_lettres.git
```
### Example
It is better to have your number in strings, this avoids conversion error between `int` or `float` and strings (see [floating point precision](https://docs.python.org/3/tutorial/floatingpoint.html) for more details).
```python
import nombres_vers_lettres as nvl
from nombres_vers_lettres import constants
# List available languages
print(f"{constants.AVAILABLE_LANGUAGES = }")
# List available currencies
print(f"{constants.CURRENCY_FORMS_FR_CODES = }")
# Print the number 42 in French (cardinal mode, new orthographe)
# Default language is fr_BE
cardinal_42 = nvl.make_letters(
42, language="fr_FR", post_1990_orthographe=True
)
print(f"{cardinal_42 = }")
# Print 42e in French (cardinal mode, new orthographe)
ordinal_nominal_42 = nvl.make_letters(
42, language="fr_FR", mode="ordinal_nominal", post_1990_orthographe=True
)
print(f"{ordinal_nominal_42 = }")
# Print €420,69 in French (new orthographe)
currency_420_69 = nvl.make_letters(
"420,69",
language="fr_FR",
mode="EUR",
post_1990_orthographe=True,
# By default, non-breaking spaces are used
use_non_breaking_spaces=False,
)
print(f"{currency_420_69 = }")
# Write 1st feminine plural
ordinal_nominal_1st_f_p = nvl.make_letters(
"1",
language="fr_FR",
mode="ordinal_nominal",
gender="feminine",
plural=True,
post_1990_orthographe=True,
)
print(f"{ordinal_nominal_1st_f_p = }")
```
### Script usage
After installing this package, Python gives you access to two entry points: `nombres_vers_lettres` or `nvl`.
```bash
$ nvl -h
usage: nvl [-h] [--mode MODE | --cardinal | --ordinal | --ordinal_nominal] [--gender GENDER | --masculine | --feminine] [--plural]
[--post_1990_orthographe] [--language LANGUAGE]
number
positional arguments:
number The number as a string to convert to letters (in French)
options:
-h, --help show this help message and exit
--mode MODE The mode to use for the conversion (nominal, cardinal or ordinal)
--cardinal, -c Convert the number to cardinal numbers in letters (e.g., 'un chat', 'deux ânes', 'quatre-vingts chats', 'deux-cents
billes', etc.)
--ordinal, -o Convert the number to ordinal numbers in letters (e.g., 'la page un', 'la page quatre-vingt', 'la page deux-cent', etc.)
--ordinal_nominal, -on
Convert the number to ordinal nominal numbers in letters (e.g., 'la quatre-vingtième page', 'la deux-centième page',
etc.)
--gender GENDER, -g GENDER
The gender to use for the conversion (feminine, féminin, feminin, f or masculine, masculin, m), default is masculine
(only has an effect on cardinal and ordinal_nominal modes)
--masculine, -m Convert the number to masculine letters (e.g. 'un' -> 'un')
--feminine, -f Convert the number to feminine letters (e.g. 'un' -> 'une')
--plural, -p Convert the number to plural letters (e.g. 'un' -> 'uns'), only has an effect on cardinal and ordinal_nominal modes
--post_1990_orthographe, -t
Use the tiret character everywhere (e.g. 'vingt-et-un')
--language LANGUAGE, -l LANGUAGE
The language code to use for the conversion (e.g. fr_BE, fr_CD, fr_FR, fr_CA, fr_CH, fr_IT)
```
## How to contribute
If you spotted an error, you can [open an issue in this repository](https://github.com/Vincent-Stragier/nombres_vers_lettres/issues/new/choose). Moreover, you can help to fix [**`num2words`**](https://github.com/savoirfairelinux/num2words).
And you can also open Pull Request for this repository.
After locally cloning your fork of this repository, you can install all the tools needed to check the code:
```bash
python -m pip install -r requirements-dev.txt
# Ideally, also install the pre-commit hooks,
# which will be executed before each commit
precommit install
```
### Pre-commit
If you cannot manage to commit your code due to the pre-commit hooks, simply uninstall them (`precommit uninstall`).
You can still manually run them using `precommit run -a -v` to see where the issues are.
### Coverage
Some tests have been implemented to check if you broke the current code. Ideally, you should add new test before changing the codebase to check if it indeed solves the issue, etc. Those tests are run by the pre-commit hooks.
#### Run the tests
```bash
coverage run -m pytest
```
#### Get some simple coverage information
```bash
coverage report
```
#### Generate an HTML report of the test coverage
```bash
coverage html
```
## Some references
Important references are in italic.
- [Writing numbers in letters according to Le Figaro](https://leconjugueur.lefigaro.fr/frlesnombres.php)
- [Writing numbers in euros according to Le Figaro](https://leconjugueur.lefigaro.fr/frlesnombreseneuros.php)
- [How to write numbers in French according to Bescherelle](https://www.bescherelle.com/faq/comment-ecrire-les-nombres-en-lettres/)
- [How to write numbers in Canadian pteFrench according to Bescherelle](https://bescherelle.ca/ecriture-des-nombres/)
- [_How to write numbers in French according to Wikipedia_](https://fr.wikipedia.org/wiki/Nombres_en_fran%C3%A7ais#Apr%C3%A8s_la_virgule) ←
- [_How to write big numbers in French according to Wikipedia_](https://fr.wikipedia.org/wiki/Noms_des_grands_nombres) ←
- [_How to write ordinal numbers according to Lingolia_](https://francais.lingolia.com/fr/vocabulaire/nombres-date-et-heure/les-nombres-ordinaux) ←
- [How to write cardinal numbers according to Lingolia](https://francais.lingolia.com/fr/vocabulaire/nombres-date-et-heure/les-nombres-cardinaux)
Raw data
{
"_id": null,
"home_page": "https://github.com/Vincent-Stragier/nombres_vers_lettres",
"name": "nombres-vers-lettres",
"maintainer": "",
"docs_url": null,
"requires_python": "<4,>=3.10",
"maintainer_email": "",
"keywords": "",
"author": "Vincent Stragier",
"author_email": "vincent.stragier@outlook.com",
"download_url": "https://files.pythonhosted.org/packages/21/e4/90e2426f08ec480031ee65bd13b87bda9383fa71f870c0e1eac791840b1a/nombres_vers_lettres-1.0.1.tar.gz",
"platform": null,
"description": "# nombres_vers_lettres\r\n\r\nA Python package to write numbers in French, with a simple script. The reason I made this package is the complexity of this simple task that often lead the implementation of such a tool to produce erroneous results (see [this issue](https://github.com/savoirfairelinux/num2words/issues/532)).\r\n\r\n## Installation\r\n\r\nYou can easily install this package using `pip`.\r\n\r\n```bash\r\npython -m pip install nombres_vers_lettres\r\n```\r\n\r\nOr for the development version:\r\n\r\n```bash\r\npython -m pip install git+https://github.com/Vincent-Stragier/nombres_vers_lettres.git\r\n```\r\n\r\n### Example\r\n\r\nIt is better to have your number in strings, this avoids conversion error between `int` or `float` and strings (see [floating point precision](https://docs.python.org/3/tutorial/floatingpoint.html) for more details).\r\n\r\n```python\r\nimport nombres_vers_lettres as nvl\r\nfrom nombres_vers_lettres import constants\r\n\r\n# List available languages\r\nprint(f\"{constants.AVAILABLE_LANGUAGES = }\")\r\n\r\n# List available currencies\r\nprint(f\"{constants.CURRENCY_FORMS_FR_CODES = }\")\r\n\r\n# Print the number 42 in French (cardinal mode, new orthographe)\r\n# Default language is fr_BE\r\ncardinal_42 = nvl.make_letters(\r\n 42, language=\"fr_FR\", post_1990_orthographe=True\r\n)\r\n\r\nprint(f\"{cardinal_42 = }\")\r\n\r\n# Print 42e in French (cardinal mode, new orthographe)\r\nordinal_nominal_42 = nvl.make_letters(\r\n 42, language=\"fr_FR\", mode=\"ordinal_nominal\", post_1990_orthographe=True\r\n)\r\n\r\nprint(f\"{ordinal_nominal_42 = }\")\r\n\r\n# Print \u20ac420,69 in French (new orthographe)\r\ncurrency_420_69 = nvl.make_letters(\r\n \"420,69\",\r\n language=\"fr_FR\",\r\n mode=\"EUR\",\r\n post_1990_orthographe=True,\r\n # By default, non-breaking spaces are used\r\n use_non_breaking_spaces=False,\r\n)\r\n\r\nprint(f\"{currency_420_69 = }\")\r\n\r\n# Write 1st feminine plural\r\nordinal_nominal_1st_f_p = nvl.make_letters(\r\n \"1\",\r\n language=\"fr_FR\",\r\n mode=\"ordinal_nominal\",\r\n gender=\"feminine\",\r\n plural=True,\r\n post_1990_orthographe=True,\r\n)\r\nprint(f\"{ordinal_nominal_1st_f_p = }\")\r\n\r\n```\r\n\r\n### Script usage\r\n\r\nAfter installing this package, Python gives you access to two entry points: `nombres_vers_lettres` or `nvl`.\r\n\r\n```bash\r\n$ nvl -h\r\nusage: nvl [-h] [--mode MODE | --cardinal | --ordinal | --ordinal_nominal] [--gender GENDER | --masculine | --feminine] [--plural]\r\n [--post_1990_orthographe] [--language LANGUAGE]\r\n number\r\n\r\npositional arguments:\r\n number The number as a string to convert to letters (in French)\r\n\r\noptions:\r\n -h, --help show this help message and exit\r\n --mode MODE The mode to use for the conversion (nominal, cardinal or ordinal)\r\n --cardinal, -c Convert the number to cardinal numbers in letters (e.g., 'un chat', 'deux \u00e2nes', 'quatre-vingts chats', 'deux-cents\r\n billes', etc.)\r\n --ordinal, -o Convert the number to ordinal numbers in letters (e.g., 'la page un', 'la page quatre-vingt', 'la page deux-cent', etc.)\r\n --ordinal_nominal, -on\r\n Convert the number to ordinal nominal numbers in letters (e.g., 'la quatre-vingti\u00e8me page', 'la deux-centi\u00e8me page',\r\n etc.)\r\n --gender GENDER, -g GENDER\r\n The gender to use for the conversion (feminine, f\u00e9minin, feminin, f or masculine, masculin, m), default is masculine\r\n (only has an effect on cardinal and ordinal_nominal modes)\r\n --masculine, -m Convert the number to masculine letters (e.g. 'un' -> 'un')\r\n --feminine, -f Convert the number to feminine letters (e.g. 'un' -> 'une')\r\n --plural, -p Convert the number to plural letters (e.g. 'un' -> 'uns'), only has an effect on cardinal and ordinal_nominal modes\r\n --post_1990_orthographe, -t\r\n Use the tiret character everywhere (e.g. 'vingt-et-un')\r\n --language LANGUAGE, -l LANGUAGE\r\n The language code to use for the conversion (e.g. fr_BE, fr_CD, fr_FR, fr_CA, fr_CH, fr_IT)\r\n```\r\n\r\n## How to contribute\r\n\r\nIf you spotted an error, you can [open an issue in this repository](https://github.com/Vincent-Stragier/nombres_vers_lettres/issues/new/choose). Moreover, you can help to fix [**`num2words`**](https://github.com/savoirfairelinux/num2words).\r\n\r\nAnd you can also open Pull Request for this repository.\r\n\r\nAfter locally cloning your fork of this repository, you can install all the tools needed to check the code:\r\n\r\n```bash\r\npython -m pip install -r requirements-dev.txt\r\n\r\n# Ideally, also install the pre-commit hooks,\r\n# which will be executed before each commit\r\nprecommit install\r\n```\r\n\r\n### Pre-commit\r\n\r\nIf you cannot manage to commit your code due to the pre-commit hooks, simply uninstall them (`precommit uninstall`).\r\n\r\nYou can still manually run them using `precommit run -a -v` to see where the issues are.\r\n\r\n### Coverage\r\n\r\nSome tests have been implemented to check if you broke the current code. Ideally, you should add new test before changing the codebase to check if it indeed solves the issue, etc. Those tests are run by the pre-commit hooks.\r\n\r\n#### Run the tests\r\n\r\n```bash\r\ncoverage run -m pytest\r\n```\r\n\r\n#### Get some simple coverage information\r\n\r\n```bash\r\ncoverage report\r\n```\r\n\r\n#### Generate an HTML report of the test coverage\r\n\r\n```bash\r\ncoverage html\r\n```\r\n\r\n## Some references\r\n\r\nImportant references are in italic.\r\n\r\n- [Writing numbers in letters according to Le Figaro](https://leconjugueur.lefigaro.fr/frlesnombres.php)\r\n- [Writing numbers in euros according to Le Figaro](https://leconjugueur.lefigaro.fr/frlesnombreseneuros.php)\r\n- [How to write numbers in French according to Bescherelle](https://www.bescherelle.com/faq/comment-ecrire-les-nombres-en-lettres/)\r\n- [How to write numbers in Canadian pteFrench according to Bescherelle](https://bescherelle.ca/ecriture-des-nombres/)\r\n- [_How to write numbers in French according to Wikipedia_](https://fr.wikipedia.org/wiki/Nombres_en_fran%C3%A7ais#Apr%C3%A8s_la_virgule) \u2190\r\n- [_How to write big numbers in French according to Wikipedia_](https://fr.wikipedia.org/wiki/Noms_des_grands_nombres) \u2190\r\n- [_How to write ordinal numbers according to Lingolia_](https://francais.lingolia.com/fr/vocabulaire/nombres-date-et-heure/les-nombres-ordinaux) \u2190\r\n- [How to write cardinal numbers according to Lingolia](https://francais.lingolia.com/fr/vocabulaire/nombres-date-et-heure/les-nombres-cardinaux)\r\n",
"bugtrack_url": null,
"license": "",
"summary": "A Python package to convert numbers to letters (in French).",
"version": "1.0.1",
"project_urls": {
"Bug Tracker": "https://github.com/Vincent-Stragier/nombres_vers_lettres/issues",
"Homepage": "https://github.com/Vincent-Stragier/nombres_vers_lettres"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "9a924b289da2dd8885d782560b37994b20903133b475e2521c7d1d395ab049f6",
"md5": "0187a33025900769d2794841acd6c982",
"sha256": "f26b18a5fe6051634a3c81a92d9ca232d837ec32d1c57ade5afc0d2e7c7da86c"
},
"downloads": -1,
"filename": "nombres_vers_lettres-1.0.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "0187a33025900769d2794841acd6c982",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<4,>=3.10",
"size": 15061,
"upload_time": "2023-08-27T14:11:05",
"upload_time_iso_8601": "2023-08-27T14:11:05.862330Z",
"url": "https://files.pythonhosted.org/packages/9a/92/4b289da2dd8885d782560b37994b20903133b475e2521c7d1d395ab049f6/nombres_vers_lettres-1.0.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "21e490e2426f08ec480031ee65bd13b87bda9383fa71f870c0e1eac791840b1a",
"md5": "aa5e825f003821cbc6def7fab7f5dbcb",
"sha256": "d976a9ba9b89094a95edd15e836b07404e8a2e02dab2d2000aee9f2110e7f12f"
},
"downloads": -1,
"filename": "nombres_vers_lettres-1.0.1.tar.gz",
"has_sig": false,
"md5_digest": "aa5e825f003821cbc6def7fab7f5dbcb",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<4,>=3.10",
"size": 15996,
"upload_time": "2023-08-27T14:11:08",
"upload_time_iso_8601": "2023-08-27T14:11:08.691831Z",
"url": "https://files.pythonhosted.org/packages/21/e4/90e2426f08ec480031ee65bd13b87bda9383fa71f870c0e1eac791840b1a/nombres_vers_lettres-1.0.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-08-27 14:11:08",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "Vincent-Stragier",
"github_project": "nombres_vers_lettres",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [],
"lcname": "nombres-vers-lettres"
}
JSON
