# PersianTools
[](https://pypi.org/project/persiantools/)
[](https://results.pre-commit.ci/latest/github/majiidd/persiantools/master)
[](https://codecov.io/gh/majiidd/persiantools)
[](https://pypi.org/project/persiantools/)
[](https://pypi.org/project/persiantools/)
PersianTools provides comprehensive tools for handling Jalali (Shamsi or Persian) dates, date-time functionalities, and more.
- Conversion between Jalali and Gregorian dates/datetimes using Python's native datetime module.
- Full support for operations like `+`, `-`, `==`, and `>=`.
- Timezone-aware date and datetime handling.
- Conversion between Persian and Arabic characters and digits.
- Conversion of numbers to their Persian word representation.
## Install Package
You can install the package using pip with the following command:
```bash
python -m pip install persiantools
```
## Usage Guide
### Date Operations
```python
>>> from persiantools.jdatetime import JalaliDate
>>> import datetime
# Get today's date in Jalali
>>> JalaliDate.today()
JalaliDate(1403, 8, 18, Jomeh)
>>> JalaliDate(1367, 2, 14)
JalaliDate(1367, 2, 14, Chaharshanbeh)
# Convert Gregorian to Jalali
>>> JalaliDate(datetime.date(1988, 5, 4))
JalaliDate(1367, 2, 14, Chaharshanbeh)
# Convert from Gregorian to Jalali using method
>>> JalaliDate.to_jalali(2013, 9, 16)
JalaliDate(1392, 6, 25, Doshanbeh)
# Convert from Jalali to Gregorian
>>> JalaliDate(1392, 6, 25).to_gregorian()
datetime.date(2013, 9, 16)
# Create a Jalali date from a Unix timestamp
>>> JalaliDate.fromtimestamp(578707200)
JalaliDate(1367, 2, 14, Chaharshanbeh)
```
### Datetime Operations
```python
>>> from persiantools.jdatetime import JalaliDateTime
>>> import datetime, pytz
# Get the current Jalali datetime
>>> JalaliDateTime.now()
JalaliDateTime(1403, 8, 18, 12, 48, 54, 569082)
# Convert Jalali datetime to Gregorian
>>> JalaliDateTime.now().to_gregorian()
datetime.datetime(2024, 11, 8, 12, 48, 54, 569082)
# Convert Gregorian datetime to Jalali
>>> JalaliDateTime.to_jalali(datetime.datetime(1988, 5, 4, 14, 0, 0, 0))
JalaliDateTime(1367, 2, 14, 14, 0)
# Create a timezone-aware Jalali datetime from a timestamp
>>> JalaliDateTime.fromtimestamp(578723400, pytz.timezone("Asia/Tehran"))
JalaliDateTime(1367, 2, 14, 8, 0, tzinfo=<DstTzInfo 'Asia/Tehran' +0330+3:30:00 STD>)
>>> JalaliDateTime.now(pytz.utc)
JalaliDateTime(1395, 4, 17, 21, 23, 53, 474618, tzinfo=<UTC>)
```
### Formatting
Based on python `strftime()` behavior
```python
>>> from persiantools.jdatetime import JalaliDate, JalaliDateTime
>>> import pytz
# ISO formatting
>>> JalaliDate(1367, 2, 14).isoformat()
'1367-02-14'
# Custom date formatting
>>> JalaliDate(1395, 3, 1).strftime("%Y/%m/%d")
'1395/03/01'
# Custom datetime formatting
>>> JalaliDateTime(1369, 7, 1, 14, 0, 10, 0, pytz.utc).strftime("%c")
'Yekshanbeh 01 Mehr 1369 14:00:10'
```
### Digits and Character Conversion
```python
>>> from persiantools import characters, digits
# Convert English digits to Persian
>>> digits.en_to_fa("0987654321")
'۰۹۸۷۶۵۴۳۲۱'
# Convert Arabic digits to Persian
>>> digits.ar_to_fa("٠٩٨٧٦٥٤٣٢١")
'۰۹۸۷۶۵۴۳۲۱'
# Convert Persian digits to English
>>> digits.fa_to_en("۰۹۸۷۶۵۴۳۲۱")
'0987654321'
# Convert numbers to Persian words
>>> digits.to_word(9512026)
'نه میلیون و پانصد و دوازده هزار و بیست و شش'
>>> digits.to_word(15.007)
'پانزده و هفت هزارم'
# Convert Arabic to Persian characters
>>> characters.ar_to_fa("كيك")
'کیک'
```
### Operators
The package supports various operators for date and time manipulations. Here are some examples:
```python
>>> from persiantools.jdatetime import JalaliDate, JalaliDateTime
>>> import datetime
>>> JalaliDate(1367, 2, 14) == JalaliDate(datetime.date(1988, 5, 4))
True
>>> JalaliDateTime(1367, 2, 14, 4, 30) >= JalaliDateTime(1368, 2, 14, 1, 0)
False
>>> JalaliDate(1367, 2, 14) == datetime.date(1988, 5, 4)
True
>>> JalaliDate(1395, 2, 14) + datetime.timedelta(days=38)
JalaliDate(1395, 3, 21, Jomeh)
>>> JalaliDateTime(1395, 12, 30) - JalaliDateTime(1395, 1, 1)
datetime.timedelta(365)
```
### Serializing and Deserializing
```python
>>> from persiantools.jdatetime import JalaliDate
>>> import pickle
# Serialize a Jalali date to a file
>>> with open("save.p", "wb") as file:
>>> pickle.dump(JalaliDate(1367, 2, 14), file)
# Deserialize from a file
>>> with open("save.p", "rb") as file:
>>> jalali = pickle.load(file)
>>> jalali
JalaliDate(1367, 2, 14, Chaharshanbeh)
```
Raw data
{
"_id": null,
"home_page": "https://github.com/majiidd/persiantools",
"name": "persiantools",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.9",
"maintainer_email": null,
"keywords": "jalali shamsi persian digits characters converter jalalidate jalalidatetime date datetime jdate jdatetime farsi",
"author": "Majid Hajiloo",
"author_email": "majid.hajiloo@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/fc/4e/714936f8aae1e1374318efee8a7b533b712f3be7c5c17d7f621434f375ce/persiantools-5.1.0.tar.gz",
"platform": null,
"description": "# PersianTools\n\n[](https://pypi.org/project/persiantools/)\n\n[](https://results.pre-commit.ci/latest/github/majiidd/persiantools/master)\n[](https://codecov.io/gh/majiidd/persiantools)\n[](https://pypi.org/project/persiantools/)\n[](https://pypi.org/project/persiantools/)\n\nPersianTools provides comprehensive tools for handling Jalali (Shamsi or Persian) dates, date-time functionalities, and more.\n- Conversion between Jalali and Gregorian dates/datetimes using Python's native datetime module.\n- Full support for operations like `+`, `-`, `==`, and `>=`.\n- Timezone-aware date and datetime handling.\n- Conversion between Persian and Arabic characters and digits.\n- Conversion of numbers to their Persian word representation.\n\n## Install Package\nYou can install the package using pip with the following command:\n```bash\npython -m pip install persiantools\n```\n\n## Usage Guide\n\n### Date Operations\n\n```python\n>>> from persiantools.jdatetime import JalaliDate\n>>> import datetime\n\n# Get today's date in Jalali\n>>> JalaliDate.today()\nJalaliDate(1403, 8, 18, Jomeh)\n\n>>> JalaliDate(1367, 2, 14)\nJalaliDate(1367, 2, 14, Chaharshanbeh)\n\n# Convert Gregorian to Jalali\n>>> JalaliDate(datetime.date(1988, 5, 4))\nJalaliDate(1367, 2, 14, Chaharshanbeh)\n\n# Convert from Gregorian to Jalali using method\n>>> JalaliDate.to_jalali(2013, 9, 16)\nJalaliDate(1392, 6, 25, Doshanbeh)\n\n# Convert from Jalali to Gregorian\n>>> JalaliDate(1392, 6, 25).to_gregorian()\ndatetime.date(2013, 9, 16)\n\n# Create a Jalali date from a Unix timestamp\n>>> JalaliDate.fromtimestamp(578707200)\nJalaliDate(1367, 2, 14, Chaharshanbeh)\n```\n\n### Datetime Operations\n\n```python\n>>> from persiantools.jdatetime import JalaliDateTime\n>>> import datetime, pytz\n\n# Get the current Jalali datetime\n>>> JalaliDateTime.now()\nJalaliDateTime(1403, 8, 18, 12, 48, 54, 569082)\n\n# Convert Jalali datetime to Gregorian\n>>> JalaliDateTime.now().to_gregorian()\ndatetime.datetime(2024, 11, 8, 12, 48, 54, 569082)\n\n# Convert Gregorian datetime to Jalali\n>>> JalaliDateTime.to_jalali(datetime.datetime(1988, 5, 4, 14, 0, 0, 0))\nJalaliDateTime(1367, 2, 14, 14, 0)\n\n# Create a timezone-aware Jalali datetime from a timestamp\n>>> JalaliDateTime.fromtimestamp(578723400, pytz.timezone(\"Asia/Tehran\"))\nJalaliDateTime(1367, 2, 14, 8, 0, tzinfo=<DstTzInfo 'Asia/Tehran' +0330+3:30:00 STD>)\n\n>>> JalaliDateTime.now(pytz.utc)\nJalaliDateTime(1395, 4, 17, 21, 23, 53, 474618, tzinfo=<UTC>)\n```\n\n### Formatting\n\nBased on python `strftime()` behavior\n\n```python\n>>> from persiantools.jdatetime import JalaliDate, JalaliDateTime\n>>> import pytz\n\n# ISO formatting\n>>> JalaliDate(1367, 2, 14).isoformat()\n'1367-02-14'\n\n# Custom date formatting\n>>> JalaliDate(1395, 3, 1).strftime(\"%Y/%m/%d\")\n'1395/03/01'\n\n# Custom datetime formatting\n>>> JalaliDateTime(1369, 7, 1, 14, 0, 10, 0, pytz.utc).strftime(\"%c\")\n'Yekshanbeh 01 Mehr 1369 14:00:10'\n```\n\n### Digits and Character Conversion\n\n```python\n>>> from persiantools import characters, digits\n\n# Convert English digits to Persian\n>>> digits.en_to_fa(\"0987654321\")\n'\u06f0\u06f9\u06f8\u06f7\u06f6\u06f5\u06f4\u06f3\u06f2\u06f1'\n\n# Convert Arabic digits to Persian\n>>> digits.ar_to_fa(\"\u0660\u0669\u0668\u0667\u0666\u0665\u0664\u0663\u0662\u0661\")\n'\u06f0\u06f9\u06f8\u06f7\u06f6\u06f5\u06f4\u06f3\u06f2\u06f1'\n\n# Convert Persian digits to English\n>>> digits.fa_to_en(\"\u06f0\u06f9\u06f8\u06f7\u06f6\u06f5\u06f4\u06f3\u06f2\u06f1\")\n'0987654321'\n\n# Convert numbers to Persian words\n>>> digits.to_word(9512026)\n'\u0646\u0647 \u0645\u06cc\u0644\u06cc\u0648\u0646 \u0648 \u067e\u0627\u0646\u0635\u062f \u0648 \u062f\u0648\u0627\u0632\u062f\u0647 \u0647\u0632\u0627\u0631 \u0648 \u0628\u06cc\u0633\u062a \u0648 \u0634\u0634'\n\n>>> digits.to_word(15.007)\n'\u067e\u0627\u0646\u0632\u062f\u0647 \u0648 \u0647\u0641\u062a \u0647\u0632\u0627\u0631\u0645'\n\n# Convert Arabic to Persian characters\n>>> characters.ar_to_fa(\"\u0643\u064a\u0643\")\n'\u06a9\u06cc\u06a9'\n```\n\n### Operators\nThe package supports various operators for date and time manipulations. Here are some examples:\n```python\n>>> from persiantools.jdatetime import JalaliDate, JalaliDateTime\n>>> import datetime\n\n>>> JalaliDate(1367, 2, 14) == JalaliDate(datetime.date(1988, 5, 4))\nTrue\n\n>>> JalaliDateTime(1367, 2, 14, 4, 30) >= JalaliDateTime(1368, 2, 14, 1, 0)\nFalse\n\n>>> JalaliDate(1367, 2, 14) == datetime.date(1988, 5, 4)\nTrue\n\n>>> JalaliDate(1395, 2, 14) + datetime.timedelta(days=38)\nJalaliDate(1395, 3, 21, Jomeh)\n\n>>> JalaliDateTime(1395, 12, 30) - JalaliDateTime(1395, 1, 1)\ndatetime.timedelta(365)\n```\n\n### Serializing and Deserializing\n\n```python\n>>> from persiantools.jdatetime import JalaliDate\n>>> import pickle\n\n# Serialize a Jalali date to a file\n>>> with open(\"save.p\", \"wb\") as file:\n>>> pickle.dump(JalaliDate(1367, 2, 14), file)\n\n# Deserialize from a file\n>>> with open(\"save.p\", \"rb\") as file:\n>>> jalali = pickle.load(file)\n>>> jalali\nJalaliDate(1367, 2, 14, Chaharshanbeh)\n```\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Jalali date and datetime with other tools",
"version": "5.1.0",
"project_urls": {
"Homepage": "https://github.com/majiidd/persiantools"
},
"split_keywords": [
"jalali",
"shamsi",
"persian",
"digits",
"characters",
"converter",
"jalalidate",
"jalalidatetime",
"date",
"datetime",
"jdate",
"jdatetime",
"farsi"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "76fa250e12792d9cbd805809564fd4c522eeb409536b51ca119c41b9cd2d364e",
"md5": "fd698e4ff169c066918ec49908211d39",
"sha256": "e96f0dbeff1e119b26c964dbbd4f7e1a058a7968c4376dfe3f5075070b4911e3"
},
"downloads": -1,
"filename": "persiantools-5.1.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "fd698e4ff169c066918ec49908211d39",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9",
"size": 21431,
"upload_time": "2024-11-08T14:03:12",
"upload_time_iso_8601": "2024-11-08T14:03:12.246991Z",
"url": "https://files.pythonhosted.org/packages/76/fa/250e12792d9cbd805809564fd4c522eeb409536b51ca119c41b9cd2d364e/persiantools-5.1.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "fc4e714936f8aae1e1374318efee8a7b533b712f3be7c5c17d7f621434f375ce",
"md5": "7b768ce7c1fcea817ba470b43fbf1cba",
"sha256": "a40e5dcce6f7c19c2e1febf4239f98c4b6203b0d09efc938e6c6c8a26d65c8a9"
},
"downloads": -1,
"filename": "persiantools-5.1.0.tar.gz",
"has_sig": false,
"md5_digest": "7b768ce7c1fcea817ba470b43fbf1cba",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9",
"size": 31431,
"upload_time": "2024-11-08T14:03:13",
"upload_time_iso_8601": "2024-11-08T14:03:13.852455Z",
"url": "https://files.pythonhosted.org/packages/fc/4e/714936f8aae1e1374318efee8a7b533b712f3be7c5c17d7f621434f375ce/persiantools-5.1.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-11-08 14:03:13",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "majiidd",
"github_project": "persiantools",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "persiantools"
}
JSON
