cosmo-intl 0.1.0__tar.gz

cosmo_intl-0.1.0/.github/workflows/test.yml

@@ -0,0 +1,27 @@
+name: Tests
+
+on:
+  push:
+  pull_request:
+  workflow_dispatch:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.9", "3.11", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+
+      # PyICU is a C extension; it needs the system ICU headers + a compiler.
+      - name: Install ICU
+        run: sudo apt-get update && sudo apt-get install -y libicu-dev pkg-config
+
+      - uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
+
+      - name: Run tests
+        run: uv run --extra test --python ${{ matrix.python-version }} pytest -q

cosmo_intl-0.1.0/.gitignore

@@ -0,0 +1,6 @@
+.venv/
+__pycache__/
+*.egg-info/
+.pytest_cache/
+build/
+dist/

cosmo_intl-0.1.0/PKG-INFO

@@ -0,0 +1,109 @@
+Metadata-Version: 2.4
+Name: cosmo-intl
+Version: 0.1.0
+Summary: Ergonomic internationalization (i18n) and localization (l10n) for Python — format numbers, currency, dates, times, units, lists and ICU plurals for any locale, powered by ICU and Unicode CLDR via PyICU. No bundled locale data.
+Project-URL: Homepage, https://github.com/cosmo-intl/cosmo-python
+Project-URL: Repository, https://github.com/cosmo-intl/cosmo-python
+Project-URL: PHP port, https://github.com/cosmo-intl/cosmo-php
+Author-email: Miloun <cosmo-python@miloun.com>
+License: MIT
+Keywords: cldr,currency,date,datetime,i18n,icu,internationalisation,internationalization,intl,l10n,locale,localisation,localization,money,pluralization,pyicu,timezone,translation,unicode
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Topic :: Software Development :: Internationalization
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: Software Development :: Localization
+Requires-Python: >=3.9
+Requires-Dist: pyicu>=2.10
+Provides-Extra: test
+Requires-Dist: pytest>=7; extra == 'test'
+Description-Content-Type: text/markdown
+
+# Cosmo
+
+Ergonomic application localisation for Python, powered by [ICU](https://icu.unicode.org/).
+
+Cosmo is a thin, ergonomic layer over **ICU**, reached through
+[PyICU](https://gitlab.pyicu.org/main/pyicu). Give it a locale (and optionally a
+time zone) and it formats numbers, money, dates, units, lists and messages exactly
+the way your users expect. There is **no bundled locale data** — every result comes
+straight from ICU and [CLDR](https://cldr.unicode.org/), covering all languages,
+scripts, calendars and time zones.
+
+Cosmo is implemented consistently across four languages — the same concepts, method
+names and behaviour, each built directly on its platform's ICU:
+[JavaScript](https://github.com/cosmo-intl/cosmo-js) ([docs](https://cosmo.miloun.com/?lang=js)) ·
+**Python** ·
+[Java](https://github.com/cosmo-intl/cosmo-java) ([docs](https://cosmo.miloun.com/?lang=java)) ·
+[PHP](https://github.com/salarmehr/cosmopolitan) ([docs](https://cosmo.miloun.com/?lang=php)).
+
+📖 **Full documentation, API reference and live playground:** https://cosmo.miloun.com/?lang=python
+
+## Requirements
+
+- Python 3.9+
+- System ICU development libraries for PyICU (e.g. `libicu-dev` + `pkg-config`)
+
+## Install
+
+```bash
+pip install cosmo-intl        # pulls in PyICU; the import package is `cosmo`
+```
+
+## Quick start
+
+```python
+from cosmo import Cosmo
+
+Cosmo("es_ES").money(11000.4, "EUR")                       # "11.000,40 €"
+Cosmo("en").percentage(0.2)                                # "20%"
+Cosmo("en_AU").money(1234.5)                               # "$1,234.50"  (currency inferred)
+Cosmo("en").spellout(42)                                   # "forty-two"
+Cosmo("fa").language("en")                                 # "انگلیسی"
+```
+
+All methods are `snake_case`. Underscore locales (`en_AU`) and [BCP-47](https://www.rfc-editor.org/info/bcp47)
+[Unicode extensions](https://unicode.org/reports/tr35/#u_Extension)
+(`fa-IR-u-nu-latn-ca-buddhist`) are both accepted.
+
+## What you get
+
+- **Locale display names** — languages, regions, scripts, calendars and currencies, plus emoji flags and writing direction.
+- **Numbers & money** — decimals, percentages, currencies (inferred from the region), units, compact notation, scientific, ranges, plus spelled-out and ordinal text.
+- **Dates & times** — locale formats in any calendar (Gregorian, Persian, Buddhist…), custom ICU patterns, durations, date ranges, and relative times.
+- **Text** — locale-aware sort and search, word/sentence/grapheme segmentation, case mapping and quotation marks.
+- **Messages** — [ICU MessageFormat](https://unicode-org.github.io/icu/userguide/format_parse/messages/) (`plural`, `selectordinal`, `select`).
+- **Parsing & transforms** — the inverse formatters for numbers, money and dates, transliteration, UTS #39 spoof checks, locale negotiation and contact-list index buckets.
+- **Raw ICU access** — resource-bundle lookups for data the high-level methods don't cover.
+
+See the [full API reference](https://cosmo.miloun.com/api-reference/?lang=python) for every method,
+the [platform notes](https://cosmo.miloun.com/platform-notes/) for PyICU's binding
+limits, and [resources](https://cosmo.miloun.com/resources/) for ICU/CLDR references.
+
+## Development
+
+The dev environment is managed with [uv](https://docs.astral.sh/uv/), which
+provisions a matching Python automatically. You still need the system ICU
+libraries (e.g. `libicu-dev` + `pkg-config`) for PyICU to build and link.
+
+```bash
+uv run --extra test pytest      # run the test suite
+uv build                        # build the wheel + sdist into dist/
+```
+
+`uv.lock` pins the dev/test toolchain for reproducible local runs and CI. It does
+**not** affect anyone who `pip install cosmo-intl` — they resolve from the
+dependency ranges in `pyproject.toml`.
+
+## Errors
+
+Recoverable problems raise `CosmoError`, with `InvalidArgumentError` and
+`UnsupportedError` subclasses — an invalid currency in strict mode, an unsupported
+unit, an unknown symbol name, an unformattable date, and the like.
+
+## License
+
+MIT © Aiden Adrian

cosmo_intl-0.1.0/README.md

@@ -0,0 +1,85 @@
+# Cosmo
+
+Ergonomic application localisation for Python, powered by [ICU](https://icu.unicode.org/).
+
+Cosmo is a thin, ergonomic layer over **ICU**, reached through
+[PyICU](https://gitlab.pyicu.org/main/pyicu). Give it a locale (and optionally a
+time zone) and it formats numbers, money, dates, units, lists and messages exactly
+the way your users expect. There is **no bundled locale data** — every result comes
+straight from ICU and [CLDR](https://cldr.unicode.org/), covering all languages,
+scripts, calendars and time zones.
+
+Cosmo is implemented consistently across four languages — the same concepts, method
+names and behaviour, each built directly on its platform's ICU:
+[JavaScript](https://github.com/cosmo-intl/cosmo-js) ([docs](https://cosmo.miloun.com/?lang=js)) ·
+**Python** ·
+[Java](https://github.com/cosmo-intl/cosmo-java) ([docs](https://cosmo.miloun.com/?lang=java)) ·
+[PHP](https://github.com/salarmehr/cosmopolitan) ([docs](https://cosmo.miloun.com/?lang=php)).
+
+📖 **Full documentation, API reference and live playground:** https://cosmo.miloun.com/?lang=python
+
+## Requirements
+
+- Python 3.9+
+- System ICU development libraries for PyICU (e.g. `libicu-dev` + `pkg-config`)
+
+## Install
+
+```bash
+pip install cosmo-intl        # pulls in PyICU; the import package is `cosmo`
+```
+
+## Quick start
+
+```python
+from cosmo import Cosmo
+
+Cosmo("es_ES").money(11000.4, "EUR")                       # "11.000,40 €"
+Cosmo("en").percentage(0.2)                                # "20%"
+Cosmo("en_AU").money(1234.5)                               # "$1,234.50"  (currency inferred)
+Cosmo("en").spellout(42)                                   # "forty-two"
+Cosmo("fa").language("en")                                 # "انگلیسی"
+```
+
+All methods are `snake_case`. Underscore locales (`en_AU`) and [BCP-47](https://www.rfc-editor.org/info/bcp47)
+[Unicode extensions](https://unicode.org/reports/tr35/#u_Extension)
+(`fa-IR-u-nu-latn-ca-buddhist`) are both accepted.
+
+## What you get
+
+- **Locale display names** — languages, regions, scripts, calendars and currencies, plus emoji flags and writing direction.
+- **Numbers & money** — decimals, percentages, currencies (inferred from the region), units, compact notation, scientific, ranges, plus spelled-out and ordinal text.
+- **Dates & times** — locale formats in any calendar (Gregorian, Persian, Buddhist…), custom ICU patterns, durations, date ranges, and relative times.
+- **Text** — locale-aware sort and search, word/sentence/grapheme segmentation, case mapping and quotation marks.
+- **Messages** — [ICU MessageFormat](https://unicode-org.github.io/icu/userguide/format_parse/messages/) (`plural`, `selectordinal`, `select`).
+- **Parsing & transforms** — the inverse formatters for numbers, money and dates, transliteration, UTS #39 spoof checks, locale negotiation and contact-list index buckets.
+- **Raw ICU access** — resource-bundle lookups for data the high-level methods don't cover.
+
+See the [full API reference](https://cosmo.miloun.com/api-reference/?lang=python) for every method,
+the [platform notes](https://cosmo.miloun.com/platform-notes/) for PyICU's binding
+limits, and [resources](https://cosmo.miloun.com/resources/) for ICU/CLDR references.
+
+## Development
+
+The dev environment is managed with [uv](https://docs.astral.sh/uv/), which
+provisions a matching Python automatically. You still need the system ICU
+libraries (e.g. `libicu-dev` + `pkg-config`) for PyICU to build and link.
+
+```bash
+uv run --extra test pytest      # run the test suite
+uv build                        # build the wheel + sdist into dist/
+```
+
+`uv.lock` pins the dev/test toolchain for reproducible local runs and CI. It does
+**not** affect anyone who `pip install cosmo-intl` — they resolve from the
+dependency ranges in `pyproject.toml`.
+
+## Errors
+
+Recoverable problems raise `CosmoError`, with `InvalidArgumentError` and
+`UnsupportedError` subclasses — an invalid currency in strict mode, an unsupported
+unit, an unknown symbol name, an unformattable date, and the like.
+
+## License
+
+MIT © Aiden Adrian

cosmo_intl-0.1.0/example.py

@@ -0,0 +1,28 @@
+"""Runnable tour of cosmo. `python example.py`"""
+
+import datetime
+
+from cosmo import Cosmo
+
+when = datetime.datetime(2020, 2, 2, 9, 30, tzinfo=datetime.timezone.utc)
+
+for tag in ("en_AU", "fa_IR", "de_DE"):
+    c = Cosmo(tag, {"timeZone": "UTC"})
+    print(f"\n=== {tag} ===")
+    print("language(en):  ", c.language("en"))
+    print("country/flag:  ", c.country(), c.flag())
+    print("number:        ", c.number(1234567.89))
+    print("money:         ", c.money(1234.5))
+    print("percentage:    ", c.percentage(0.1234))
+    print("compact:       ", c.compact(1_200_000, "long"))
+    print("spellout/ord:  ", c.spellout(42), "/", c.ordinal(21))
+    print("moment:        ", c.moment(when, "full", "short"))
+    print("month[0]:      ", c.month_names()[0])
+    print("relative:      ", c.relative_duration(-3, "day"))
+    print("join:          ", c.join(["apples", "pears", "figs"]))
+    print("quote:         ", c.quote("hi"))
+    print("plural(2):     ", c.plural_category(2))
+    print(
+        "message:       ",
+        c.message("{0, plural, one {# file} other {# files}}", [3]),
+    )

cosmo_intl-0.1.0/pyproject.toml

@@ -0,0 +1,60 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+# PyPI distribution name; the bare `cosmo` is taken on PyPI, so we publish as
+# `cosmo-intl` (matches the GitHub org) while the import package stays `cosmo`.
+name = "cosmo-intl"
+version = "0.1.0"
+description = "Ergonomic internationalization (i18n) and localization (l10n) for Python — format numbers, currency, dates, times, units, lists and ICU plurals for any locale, powered by ICU and Unicode CLDR via PyICU. No bundled locale data."
+readme = "README.md"
+requires-python = ">=3.9"
+license = { text = "MIT" }
+authors = [{ name = "Miloun", email = "cosmo-python@miloun.com" }]
+keywords = [
+    "i18n",
+    "l10n",
+    "internationalization",
+    "internationalisation",
+    "localization",
+    "localisation",
+    "intl",
+    "icu",
+    "cldr",
+    "unicode",
+    "locale",
+    "translation",
+    "currency",
+    "money",
+    "date",
+    "datetime",
+    "timezone",
+    "pluralization",
+    "pyicu",
+]
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3 :: Only",
+    "Topic :: Software Development :: Localization",
+    "Topic :: Software Development :: Internationalization",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+]
+dependencies = ["PyICU>=2.10"]
+
+[project.optional-dependencies]
+test = ["pytest>=7"]
+
+[project.urls]
+Homepage = "https://github.com/cosmo-intl/cosmo-python"
+Repository = "https://github.com/cosmo-intl/cosmo-python"
+"PHP port" = "https://github.com/cosmo-intl/cosmo-php"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/cosmo"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

cosmo_intl-0.1.0/src/cosmo/__init__.py

@@ -0,0 +1,15 @@
+"""Cosmo — application localisation for Python, backed entirely by ICU."""
+
+from .bundle import Bundle
+from .cosmo import Cosmo, Moment
+from .errors import CosmoError, InvalidArgumentError, UnsupportedError
+
+__all__ = [
+    "Cosmo",
+    "Bundle",
+    "CosmoError",
+    "InvalidArgumentError",
+    "UnsupportedError",
+    "Moment",
+]
+__version__ = "0.1.0"

cosmo_intl-0.1.0/src/cosmo/bundle.py

@@ -0,0 +1,18 @@
+"""Names of the ICU resource bundles reachable through :meth:`Cosmo.get`.
+
+These mirror the constants in the PHP port's ``Bundle`` class. They are the
+package identifiers PyICU's :class:`icu.ResourceBundle` understands.
+"""
+
+
+class Bundle:
+    """ICU resource-bundle package names."""
+
+    #: Break-iterator rule source data.
+    BRKITR = "ICUDATA-brkitr"
+    #: Currency symbols and display names.
+    CURRENCY = "ICUDATA-curr"
+    #: The per-locale bundle (delimiters, layout, …).
+    LOCALE = "ICUDATA"
+    #: Language / script / calendar display names.
+    LANGUAGE = "ICUDATA-lang"