# 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/)
Provides Jalali (also known as Shamsi or Persian) dates and datetimes functionalities, among other tools.
- It converts between Jalali and Gregorian dates and datetimes (based on python datetime's module).
- It supports operators like `+`, `-`, `==`, and `>=`.
- It includes timezone support.
- It converts between Arabic and Persian characters/digits.
- It turns numbers into Persian words.
## Install Package
You can install the package using pip with the following command:
```bash
python -m pip install persiantools
```
Persiantools supports Python 3.8+. (_for python 2.7 and 3.5 use [1.5.x](https://github.com/majiidd/persiantools/tree/1.5.x) version_)
## How to use
### Date
```python
>>> from persiantools.jdatetime import JalaliDate
>>> import datetime
>>> JalaliDate.today()
JalaliDate(1395, 4, 18, Jomeh)
>>> JalaliDate(1369, 7, 1)
JalaliDate(1369, 7, 1, Yekshanbeh)
>>> JalaliDate(datetime.date(1990, 9, 23)) # Gregorian to Jalali
JalaliDate(1369, 7, 1, Yekshanbeh)
>>> JalaliDate.to_jalali(2013, 9, 16) # Gregorian to Jalali
JalaliDate(1392, 6, 25, Doshanbeh)
>>> JalaliDate(1392, 6, 25).to_gregorian() # Jalali to Gregorian
datetime.date(2013, 9, 16)
>>> JalaliDate.fromtimestamp(578707200) # Timestamp to Jalali
JalaliDate(1367, 2, 14, Chaharshanbeh)
```
### Datetime
```python
>>> from persiantools.jdatetime import JalaliDateTime
>>> import datetime, pytz
>>> JalaliDateTime.now()
JalaliDateTime(1395, 4, 18, 1, 43, 24, 720505)
>>> JalaliDateTime.now().to_gregorian() # Jalali to Gregorian
datetime.datetime(2016, 7, 8, 1, 43, 24, 720505)
>>> JalaliDateTime.to_jalali(datetime.datetime(1988, 5, 4, 14, 0, 0, 0)) # Gregorian to Jalali
JalaliDateTime(1367, 2, 14, 14, 0)
>>> JalaliDateTime.fromtimestamp(578723400, pytz.timezone("Asia/Tehran")) # Timestamp to Jalali
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>)
```
### Format
Based on python `strftime()` behavior
```python
>>> from persiantools.jdatetime import JalaliDate, JalaliDateTime
>>> import pytz
>>> JalaliDate(1367, 2, 14).isoformat()
'1367-02-14'
>>> JalaliDate(1395, 3, 1).strftime("%Y/%m/%d")
'1395/03/01'
>>> JalaliDateTime(1369, 7, 1, 14, 0, 10, 0, pytz.utc).strftime("%c")
'Yekshanbeh 01 Mehr 1369 14:00:10'
>>> JalaliDateTime.now(pytz.utc).strftime("%I:%M:%S.%f %p %z %Z")
'01:49:22.518523 PM +0000 UTC'
```
### Digits/Characters Tools
```python
>>> from persiantools import characters, digits
>>> digits.en_to_fa("0987654321")
'۰۹۸۷۶۵۴۳۲۱'
>>> digits.ar_to_fa("٠٩٨٧٦٥٤٣٢١")
'۰۹۸۷۶۵۴۳۲۱'
>>> digits.fa_to_en("۰۹۸۷۶۵۴۳۲۱")
'0987654321'
>>> digits.to_word(9512026)
'نه میلیون و پانصد و دوازده هزار و بیست و شش'
>>> digits.to_word(15.007)
'پانزده و هفت هزارم'
>>> 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 de-serializing
```python
>>> from persiantools.jdatetime import JalaliDate
>>> import pickle
>>> # Serializing
>>> file = open("save.p", "wb")
>>> pickle.dump(JalaliDate(1367, 2, 14), file)
>>> file.close()
>>> # de-serializing
>>> file = open("save.p", "rb")
>>> jalali = pickle.load(file)
>>> file.close()
>>> 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.8",
"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/de/7d/4a500497eb83f72e93c4c7a674aa0a0b4f435363c450ee957e9c1895f23e/persiantools-4.0.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\nProvides Jalali (also known as Shamsi or Persian) dates and datetimes functionalities, among other tools.\n- It converts between Jalali and Gregorian dates and datetimes (based on python datetime's module).\n- It supports operators like `+`, `-`, `==`, and `>=`.\n- It includes timezone support.\n- It converts between Arabic and Persian characters/digits.\n- It turns numbers into Persian words.\n\n## Install Package\nYou can install the package using pip with the following command:\n```bash\npython -m pip install persiantools\n```\nPersiantools supports Python 3.8+. (_for python 2.7 and 3.5 use [1.5.x](https://github.com/majiidd/persiantools/tree/1.5.x) version_)\n\n## How to use\n\n### Date\n\n```python\n>>> from persiantools.jdatetime import JalaliDate\n>>> import datetime\n\n>>> JalaliDate.today()\nJalaliDate(1395, 4, 18, Jomeh)\n\n>>> JalaliDate(1369, 7, 1)\nJalaliDate(1369, 7, 1, Yekshanbeh)\n\n>>> JalaliDate(datetime.date(1990, 9, 23)) # Gregorian to Jalali\nJalaliDate(1369, 7, 1, Yekshanbeh)\n\n>>> JalaliDate.to_jalali(2013, 9, 16) # Gregorian to Jalali\nJalaliDate(1392, 6, 25, Doshanbeh)\n\n>>> JalaliDate(1392, 6, 25).to_gregorian() # Jalali to Gregorian\ndatetime.date(2013, 9, 16)\n\n>>> JalaliDate.fromtimestamp(578707200) # Timestamp to Jalali\nJalaliDate(1367, 2, 14, Chaharshanbeh)\n```\n\n### Datetime\n\n```python\n>>> from persiantools.jdatetime import JalaliDateTime\n>>> import datetime, pytz\n\n>>> JalaliDateTime.now()\nJalaliDateTime(1395, 4, 18, 1, 43, 24, 720505)\n\n>>> JalaliDateTime.now().to_gregorian() # Jalali to Gregorian\ndatetime.datetime(2016, 7, 8, 1, 43, 24, 720505)\n\n>>> JalaliDateTime.to_jalali(datetime.datetime(1988, 5, 4, 14, 0, 0, 0)) # Gregorian to Jalali\nJalaliDateTime(1367, 2, 14, 14, 0)\n\n>>> JalaliDateTime.fromtimestamp(578723400, pytz.timezone(\"Asia/Tehran\")) # Timestamp to Jalali\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### Format\n\nBased on python `strftime()` behavior\n\n```python\n>>> from persiantools.jdatetime import JalaliDate, JalaliDateTime\n>>> import pytz\n\n>>> JalaliDate(1367, 2, 14).isoformat()\n'1367-02-14'\n\n>>> JalaliDate(1395, 3, 1).strftime(\"%Y/%m/%d\")\n'1395/03/01'\n\n>>> JalaliDateTime(1369, 7, 1, 14, 0, 10, 0, pytz.utc).strftime(\"%c\")\n'Yekshanbeh 01 Mehr 1369 14:00:10'\n\n>>> JalaliDateTime.now(pytz.utc).strftime(\"%I:%M:%S.%f %p %z %Z\")\n'01:49:22.518523 PM +0000 UTC'\n```\n\n### Digits/Characters Tools\n\n```python\n>>> from persiantools import characters, digits\n\n>>> digits.en_to_fa(\"0987654321\")\n'\u06f0\u06f9\u06f8\u06f7\u06f6\u06f5\u06f4\u06f3\u06f2\u06f1'\n\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>>> digits.fa_to_en(\"\u06f0\u06f9\u06f8\u06f7\u06f6\u06f5\u06f4\u06f3\u06f2\u06f1\")\n'0987654321'\n\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>>> 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 de-serializing\n\n```python\n>>> from persiantools.jdatetime import JalaliDate\n>>> import pickle\n\n>>> # Serializing\n>>> file = open(\"save.p\", \"wb\")\n>>> pickle.dump(JalaliDate(1367, 2, 14), file)\n>>> file.close()\n\n>>> # de-serializing\n>>> file = open(\"save.p\", \"rb\")\n>>> jalali = pickle.load(file)\n>>> file.close()\n>>> jalali\nJalaliDate(1367, 2, 14, Chaharshanbeh)\n```\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Jalali date and datetime with other tools",
"version": "4.0.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": "44459339909b5ead81f087888db7a65126538e032f158a34b5260ad99f1c7bca",
"md5": "92ad06710a9a3cd606feac460cde1528",
"sha256": "24c1ef540aa738987731aa5f0e8753486bffed3fa2dc6d4a1bcb7f6e5435b1aa"
},
"downloads": -1,
"filename": "persiantools-4.0.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "92ad06710a9a3cd606feac460cde1528",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 15709,
"upload_time": "2024-03-24T15:58:20",
"upload_time_iso_8601": "2024-03-24T15:58:20.643270Z",
"url": "https://files.pythonhosted.org/packages/44/45/9339909b5ead81f087888db7a65126538e032f158a34b5260ad99f1c7bca/persiantools-4.0.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "de7d4a500497eb83f72e93c4c7a674aa0a0b4f435363c450ee957e9c1895f23e",
"md5": "8ee5fe57e89024772339d925e580abe2",
"sha256": "c6569cebd72451a59bdf2c6e39263a40cd826e00ecfcd60593b4ad736c90e650"
},
"downloads": -1,
"filename": "persiantools-4.0.0.tar.gz",
"has_sig": false,
"md5_digest": "8ee5fe57e89024772339d925e580abe2",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 22541,
"upload_time": "2024-03-24T15:58:22",
"upload_time_iso_8601": "2024-03-24T15:58:22.446738Z",
"url": "https://files.pythonhosted.org/packages/de/7d/4a500497eb83f72e93c4c7a674aa0a0b4f435363c450ee957e9c1895f23e/persiantools-4.0.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-03-24 15:58:22",
"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
