jalalix 0.1.0__tar.gz

jalalix-0.1.0/.gitignore

@@ -0,0 +1,45 @@
+# Byte-compiled / cache
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+
+# Distribution / packaging
+build/
+dist/
+*.egg-info/
+.eggs/
+*.egg
+pip-wheel-metadata/
+
+# Virtual environments
+.venv/
+venv/
+ENV/
+env/
+
+# Test / coverage
+.pytest_cache/
+.coverage
+.coverage.*
+htmlcov/
+.tox/
+.nox/
+coverage.xml
+*.cover
+
+# Type checkers / linters
+.mypy_cache/
+.ruff_cache/
+.pytype/
+.pyre/
+
+# IDE / OS
+.idea/
+.vscode/
+*.swp
+.DS_Store
+
+# Local env
+.env
+.env.*

jalalix-0.1.0/CHANGELOG.md

@@ -0,0 +1,5 @@
+# Release Notes
+All notable changes to this package will be documented in this file.
+
+## 0.1.0
+- Initial commit

jalalix-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) Hossein Maklavani
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

jalalix-0.1.0/PKG-INFO

@@ -0,0 +1,190 @@
+Metadata-Version: 2.5
+Name: jalalix
+Version: 0.1.0
+Summary: Jalali (Persian/Shamsi) calendar for Python. Pure Python, no runtime dependencies.
+Project-URL: Homepage, https://jalalix.com
+Project-URL: Documentation, https://jalalix.com
+Project-URL: Repository, https://github.com/jalalix/python
+Project-URL: Issues, https://github.com/jalalix/python/issues
+Author-email: Hossein Maklavani <hos.mohamadi@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: calendar,date,farsi,jalaali,jalali,jalalix,khorshidi,persian,python,shamsi
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.9
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# JalaliX
+
+Jalali (Persian / Shamsi) calendar for Python. Pure Python 3.9+, no runtime dependencies.
+
+[![PyPI](https://img.shields.io/pypi/v/jalalix.svg)](https://pypi.org/project/jalalix/)
+[![license](https://img.shields.io/pypi/l/jalalix.svg)](./LICENSE)
+
+```bash
+pip install jalalix
+```
+
+```python
+from jalalix import JalaliX
+
+date = JalaliX.create('2025-02-25')
+
+date.format('YYYY/MM/DD')  # 1403/12/07
+date.format('DD MMM YYYY', {'persianDigits': True})  # ۰۷ اسفند ۱۴۰۳
+
+JalaliX.parseJalali('1403/12/07').toISODate()  # 2025-02-25
+```
+
+`toISODate()` uses local calendar getters. Prefer it when you need a calendar date string without UTC shift surprises.
+
+## Install
+
+```bash
+pip install jalalix
+```
+
+```python
+from jalalix import JalaliX
+```
+
+## Usage
+
+### create / format
+
+```python
+now = JalaliX.create(datetime.now(), {'timezone': 'Asia/Tehran'})
+
+now.format('YYYY/MM/DD')
+now.format('WN، DD MMM YYYY')
+now.format('YYYY/MM/DD', {'persianDigits': True})
+now.format('DD MMM YYYY', {'calendar': 'gregorian'})
+```
+
+`format` also accepts the older positional form: `format(str, persianDigits?, gregorian?)`.
+
+### parseJalali
+
+```python
+JalaliX.parseJalali('1403/12/07')
+JalaliX.parseJalali('۱۴۰۳-۱۲-۰۷ 14:30')
+```
+
+### toISODate
+
+```python
+d = JalaliX.create('2025-02-25')
+
+d.toISODate()          # 2025-02-25  (local Gregorian getters)
+d.toISODate('jalali')  # 1403-12-07
+```
+
+### add / start / end
+
+```python
+JalaliX.create('2025-02-25').addMonths(1).getStartOfMonth().format('YYYY/MM/DD')
+```
+
+### Persian digits
+
+```python
+JalaliX.toPersian('1403/12/07')   # ۱۴۰۳/۱۲/۰۷
+JalaliX.fromPersian('۱۴۰۳/۱۲/۰۷')  # 1403/12/07
+```
+
+## Months
+
+This is easy to get wrong:
+
+- `getMonth()` -> 1..12 (Farvardin = 1)
+- `setMonth(m)` / `setFullYear(y, m)` -> 0..11, same as JS `Date` (Farvardin = 0)
+
+```python
+d = JalaliX.create(datetime.now())
+d.setFullYear(1404, 0, 1)  # 1 Farvardin 1404
+d.getMonth()  # 1
+```
+
+## Timezone
+
+Internal storage is a **UTC Unix millisecond instant** plus an IANA timezone id. `setTimezone` is **instant-preserving**: the timestamp stays the same; wall clock / Jalali day may change.
+
+```python
+d = JalaliX.create(1740430800000)
+tehran = d.setTimezone("Asia/Tehran")
+tehran.format("YYYY/MM/DD")  # 1403/12/07
+tehran.format("HH:mm:ss")    # 00:30:00
+
+utc = d.setTimezone("UTC")
+utc.format("YYYY/MM/DD")  # 1403/12/06
+utc.format("HH:mm:ss")    # 21:00:00
+```
+
+- **Aliases:** `utc` / `gmt` -> `UTC`; `local` / `default` / `system` -> host IANA zone when detectable, else `UTC`.
+- **Invalid zone** -> `ValueError`.
+- Offsets use stdlib `zoneinfo`, with a **vendored** TZif set under `jalalix/zoneinfo/` (`UTC`, `Etc/UTC`, `Asia/Tehran`, `Asia/Tokyo`, `Europe/London`, `America/New_York`) so Windows works without the PyPI `tzdata` package.
+
+## Format tokens
+
+| Token               |                                 |
+| ------------------- | ------------------------------- |
+| `YYYY` `YY`         | year                            |
+| `MMM` `MM` `M`      | month name / number             |
+| `DD` `D`            | day                             |
+| `HH` `hh` `mm` `ss` | time                            |
+| `A` `a`             | meridiem (ق.ظ. / ب.ظ. or AM/PM) |
+| `WN` `WL`           | weekday name / letter           |
+| `w` `DDD`           | week of year / day of year      |
+| `X` `x`             | unix seconds / ms               |
+
+```python
+date.format('YYYY/MM/DD')
+date.format('YYYY/MM/DD', {'persianDigits': True})
+date.format('DD MMM YYYY', {'calendar': 'gregorian'})
+```
+
+## API
+
+Static:
+
+- `create(date, options?)` — timestamp (ms), ISO string, `datetime`, or `date`
+- `parseJalali(str, options?)`
+- `isValidDate(value)`
+- `toPersian(str)` / `fromPersian(str)`
+- `compare(a, b)` — true if `a` is before `b`
+
+`options` is `{'timezone': str}` (e.g. `'Asia/Tehran'`).
+
+Instance (main ones):
+
+- `format(...)`, `toISODate(calendar?)`
+- `toString()`, `toDateString()`, `toLocaleDateString()`, `toLocaleTimeString()`
+- `getFullYear()`, `getMonth()`, `getDate()`, `getDay()`, …
+- `setFullYear`, `setMonth`, `setDate`, `setHours`, … (mutate and return `self`)
+- `addYears`, `addMonths`, `addWeeks`, `addDays`
+- `getStartOfYear` / `Month` / `Week` / `Day` and matching `getEndOf*`
+- `clone()`, `setTimezone(tz)`, `getTimezone()`
+
+Method names match the TypeScript package (camelCase).
+
+## Links
+
+- https://pypi.org/project/jalalix/
+- https://jalalix.com
+- https://github.com/jalalix/python
+- [CHANGELOG.md](./CHANGELOG.md)
+
+## License
+
+MIT

jalalix-0.1.0/README.md

@@ -0,0 +1,163 @@
+# JalaliX
+
+Jalali (Persian / Shamsi) calendar for Python. Pure Python 3.9+, no runtime dependencies.
+
+[![PyPI](https://img.shields.io/pypi/v/jalalix.svg)](https://pypi.org/project/jalalix/)
+[![license](https://img.shields.io/pypi/l/jalalix.svg)](./LICENSE)
+
+```bash
+pip install jalalix
+```
+
+```python
+from jalalix import JalaliX
+
+date = JalaliX.create('2025-02-25')
+
+date.format('YYYY/MM/DD')  # 1403/12/07
+date.format('DD MMM YYYY', {'persianDigits': True})  # ۰۷ اسفند ۱۴۰۳
+
+JalaliX.parseJalali('1403/12/07').toISODate()  # 2025-02-25
+```
+
+`toISODate()` uses local calendar getters. Prefer it when you need a calendar date string without UTC shift surprises.
+
+## Install
+
+```bash
+pip install jalalix
+```
+
+```python
+from jalalix import JalaliX
+```
+
+## Usage
+
+### create / format
+
+```python
+now = JalaliX.create(datetime.now(), {'timezone': 'Asia/Tehran'})
+
+now.format('YYYY/MM/DD')
+now.format('WN، DD MMM YYYY')
+now.format('YYYY/MM/DD', {'persianDigits': True})
+now.format('DD MMM YYYY', {'calendar': 'gregorian'})
+```
+
+`format` also accepts the older positional form: `format(str, persianDigits?, gregorian?)`.
+
+### parseJalali
+
+```python
+JalaliX.parseJalali('1403/12/07')
+JalaliX.parseJalali('۱۴۰۳-۱۲-۰۷ 14:30')
+```
+
+### toISODate
+
+```python
+d = JalaliX.create('2025-02-25')
+
+d.toISODate()          # 2025-02-25  (local Gregorian getters)
+d.toISODate('jalali')  # 1403-12-07
+```
+
+### add / start / end
+
+```python
+JalaliX.create('2025-02-25').addMonths(1).getStartOfMonth().format('YYYY/MM/DD')
+```
+
+### Persian digits
+
+```python
+JalaliX.toPersian('1403/12/07')   # ۱۴۰۳/۱۲/۰۷
+JalaliX.fromPersian('۱۴۰۳/۱۲/۰۷')  # 1403/12/07
+```
+
+## Months
+
+This is easy to get wrong:
+
+- `getMonth()` -> 1..12 (Farvardin = 1)
+- `setMonth(m)` / `setFullYear(y, m)` -> 0..11, same as JS `Date` (Farvardin = 0)
+
+```python
+d = JalaliX.create(datetime.now())
+d.setFullYear(1404, 0, 1)  # 1 Farvardin 1404
+d.getMonth()  # 1
+```
+
+## Timezone
+
+Internal storage is a **UTC Unix millisecond instant** plus an IANA timezone id. `setTimezone` is **instant-preserving**: the timestamp stays the same; wall clock / Jalali day may change.
+
+```python
+d = JalaliX.create(1740430800000)
+tehran = d.setTimezone("Asia/Tehran")
+tehran.format("YYYY/MM/DD")  # 1403/12/07
+tehran.format("HH:mm:ss")    # 00:30:00
+
+utc = d.setTimezone("UTC")
+utc.format("YYYY/MM/DD")  # 1403/12/06
+utc.format("HH:mm:ss")    # 21:00:00
+```
+
+- **Aliases:** `utc` / `gmt` -> `UTC`; `local` / `default` / `system` -> host IANA zone when detectable, else `UTC`.
+- **Invalid zone** -> `ValueError`.
+- Offsets use stdlib `zoneinfo`, with a **vendored** TZif set under `jalalix/zoneinfo/` (`UTC`, `Etc/UTC`, `Asia/Tehran`, `Asia/Tokyo`, `Europe/London`, `America/New_York`) so Windows works without the PyPI `tzdata` package.
+
+## Format tokens
+
+| Token               |                                 |
+| ------------------- | ------------------------------- |
+| `YYYY` `YY`         | year                            |
+| `MMM` `MM` `M`      | month name / number             |
+| `DD` `D`            | day                             |
+| `HH` `hh` `mm` `ss` | time                            |
+| `A` `a`             | meridiem (ق.ظ. / ب.ظ. or AM/PM) |
+| `WN` `WL`           | weekday name / letter           |
+| `w` `DDD`           | week of year / day of year      |
+| `X` `x`             | unix seconds / ms               |
+
+```python
+date.format('YYYY/MM/DD')
+date.format('YYYY/MM/DD', {'persianDigits': True})
+date.format('DD MMM YYYY', {'calendar': 'gregorian'})
+```
+
+## API
+
+Static:
+
+- `create(date, options?)` — timestamp (ms), ISO string, `datetime`, or `date`
+- `parseJalali(str, options?)`
+- `isValidDate(value)`
+- `toPersian(str)` / `fromPersian(str)`
+- `compare(a, b)` — true if `a` is before `b`
+
+`options` is `{'timezone': str}` (e.g. `'Asia/Tehran'`).
+
+Instance (main ones):
+
+- `format(...)`, `toISODate(calendar?)`
+- `toString()`, `toDateString()`, `toLocaleDateString()`, `toLocaleTimeString()`
+- `getFullYear()`, `getMonth()`, `getDate()`, `getDay()`, …
+- `setFullYear`, `setMonth`, `setDate`, `setHours`, … (mutate and return `self`)
+- `addYears`, `addMonths`, `addWeeks`, `addDays`
+- `getStartOfYear` / `Month` / `Week` / `Day` and matching `getEndOf*`
+- `clone()`, `setTimezone(tz)`, `getTimezone()`
+
+Method names match the TypeScript package (camelCase).
+
+## Links
+
+- https://pypi.org/project/jalalix/
+- https://jalalix.com
+- https://github.com/jalalix/python
+- [CHANGELOG.md](./CHANGELOG.md)
+
+## License
+
+MIT

jalalix-0.1.0/pyproject.toml

@@ -0,0 +1,55 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "jalalix"
+version = "0.1.0"
+description = "Jalali (Persian/Shamsi) calendar for Python. Pure Python, no runtime dependencies."
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.9"
+authors = [
+  { name = "Hossein Maklavani", email = "hos.mohamadi@gmail.com" },
+]
+keywords = [
+  "jalalix",
+  "jalali",
+  "jalaali",
+  "shamsi",
+  "persian",
+  "farsi",
+  "khorshidi",
+  "calendar",
+  "date",
+  "python",
+]
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "Intended Audience :: Developers",
+  "License :: OSI Approved :: MIT License",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.9",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Topic :: Software Development :: Libraries :: Python Modules",
+]
+dependencies = []
+
+[project.urls]
+Homepage = "https://jalalix.com"
+Documentation = "https://jalalix.com"
+Repository = "https://github.com/jalalix/python"
+Issues = "https://github.com/jalalix/python/issues"
+
+[project.optional-dependencies]
+dev = ["pytest>=7.0"]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/jalalix"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+pythonpath = ["src"]

jalalix-0.1.0/src/jalalix/__init__.py

@@ -0,0 +1,6 @@
+"""JalaliX — Jalali (Persian / Shamsi) calendar for Python."""
+
+from .jalalix import JalaliX
+
+__all__ = ["JalaliX"]
+__version__ = "0.1.0"