persiantools 3.0.1__tar.gz → 5.2.0__tar.gz

{persiantools-3.0.1 → persiantools-5.2.0}/LICENSE

@@ -1,6 +1,6 @@
-The MIT License (MIT)
+MIT License
 
-Copyright (c) 2016-2022 Majid Hajiloo
+Copyright (c) 2016-2025 Majid Hajiloo
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

persiantools-5.2.0/MANIFEST.in

@@ -0,0 +1 @@
+include LICENSE README.md

{persiantools-3.0.1/persiantools.egg-info → persiantools-5.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.1
+Metadata-Version: 2.2
 Name: persiantools
-Version: 3.0.1
+Version: 5.2.0
 Summary: Jalali date and datetime with other tools
 Home-page: https://github.com/majiidd/persiantools
 Author: Majid Hajiloo
@@ -13,11 +13,11 @@ Classifier: Natural Language :: Persian
 Classifier: Operating System :: OS Independent
 Classifier: Programming Language :: Python
 Classifier: Programming Language :: Python :: 3
-Classifier: Programming Language :: Python :: 3.6
-Classifier: Programming Language :: Python :: 3.7
-Classifier: Programming Language :: Python :: 3.8
 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: Programming Language :: Python :: Implementation :: CPython
 Classifier: Programming Language :: Python :: Implementation :: PyPy
 Classifier: Topic :: Software Development
@@ -25,9 +25,21 @@ Classifier: Topic :: Software Development :: Libraries
 Classifier: Topic :: Software Development :: Libraries :: Python Modules
 Classifier: Topic :: Software Development :: Localization
 Classifier: Topic :: Utilities
-Requires-Python: >=3.6
+Requires-Python: >=3.9
 Description-Content-Type: text/markdown
 License-File: LICENSE
+Requires-Dist: pytz
+Dynamic: author
+Dynamic: author-email
+Dynamic: classifier
+Dynamic: description
+Dynamic: description-content-type
+Dynamic: home-page
+Dynamic: keywords
+Dynamic: license
+Dynamic: requires-dist
+Dynamic: requires-python
+Dynamic: summary
 
 # PersianTools
 
@@ -38,72 +50,78 @@ License-File: LICENSE
 [![PyPI - Python Version](https://img.shields.io/pypi/pyversions/persiantools.svg)](https://pypi.org/project/persiantools/)
 [![PyPI - License](https://img.shields.io/pypi/l/persiantools.svg)](https://pypi.org/project/persiantools/)
 
-- Jalali (Shamsi) date and datetime (based on python datetime's module)
-
-  - Convert Jalali to Gregorian date/datetime and vice versa
-  - Support comparison and arithmetic operators such as `+`, `-`, `==`, `>=`
-  - Support timezone
-
-- Convert Arabic and Persian characters/digits to each other
-- Convert numbers to words
+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
 ```
-Persiantools supports Python 3.6+. (_for python 2.7 and 3.5 use [1.5.x](https://github.com/majiidd/persiantools/tree/1.5.x) version_)
 
-## How to use
+## Usage Guide
 
-### Date
+### Date Operations
 
 ```python
 >>> from persiantools.jdatetime import JalaliDate
 >>> import datetime
 
+# Get today's date in Jalali
 >>> JalaliDate.today()
-JalaliDate(1395, 4, 18, Jomeh)
+JalaliDate(1403, 8, 18, Jomeh)
 
->>> JalaliDate(1369, 7, 1)
-JalaliDate(1369, 7, 1, Yekshanbeh)
+>>> JalaliDate(1367, 2, 14)
+JalaliDate(1367, 2, 14, Chaharshanbeh)
 
->>> JalaliDate(datetime.date(1990, 9, 23))      # Gregorian to Jalali
-JalaliDate(1369, 7, 1, Yekshanbeh)
+# Convert Gregorian to Jalali
+>>> JalaliDate(datetime.date(1988, 5, 4))
+JalaliDate(1367, 2, 14, Chaharshanbeh)
 
->>> JalaliDate.to_jalali(2013, 9, 16)           # Gregorian to Jalali
+# Convert from Gregorian to Jalali using method
+>>> JalaliDate.to_jalali(2013, 9, 16)
 JalaliDate(1392, 6, 25, Doshanbeh)
 
->>> JalaliDate(1392, 6, 25).to_gregorian()      # Jalali to Gregorian
+# Convert from Jalali to Gregorian
+>>> JalaliDate(1392, 6, 25).to_gregorian()
 datetime.date(2013, 9, 16)
 
->>> JalaliDate.fromtimestamp(578707200)         # Timestamp to Jalali
+# Create a Jalali date from a Unix timestamp
+>>> JalaliDate.fromtimestamp(578707200)
 JalaliDate(1367, 2, 14, Chaharshanbeh)
 ```
 
-### Datetime
+### Datetime Operations
 
 ```python
 >>> from persiantools.jdatetime import JalaliDateTime
 >>> import datetime, pytz
 
+# Get the current Jalali datetime
 >>> JalaliDateTime.now()
-JalaliDateTime(1395, 4, 18, 1, 43, 24, 720505)
+JalaliDateTime(1403, 8, 18, 12, 48, 54, 569082)
 
->>> JalaliDateTime.now().to_gregorian()                                     # Jalali to Gregorian
-datetime.datetime(2016, 7, 8, 1, 43, 24, 720505)
+# Convert Jalali datetime to Gregorian
+>>> JalaliDateTime.now().to_gregorian()
+datetime.datetime(2024, 11, 8, 12, 48, 54, 569082)
 
->>> JalaliDateTime.to_jalali(datetime.datetime(1988, 5, 4, 14, 0, 0, 0))    # Gregorian to Jalali
+# Convert Gregorian datetime to Jalali
+>>> JalaliDateTime.to_jalali(datetime.datetime(1988, 5, 4, 14, 0, 0, 0))
 JalaliDateTime(1367, 2, 14, 14, 0)
 
->>> JalaliDateTime.fromtimestamp(578723400, pytz.timezone("Asia/Tehran"))   # Timestamp to Jalali
+# 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>)
 ```
 
-### Format
+### Formatting
 
 Based on python `strftime()` behavior
 
@@ -111,45 +129,50 @@ Based on python `strftime()` behavior
 >>> 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'
-
->>> JalaliDateTime.now(pytz.utc).strftime("%I:%M:%S.%f %p %z %Z")
-'01:49:22.518523 PM +0000 UTC'
 ```
 
-### Digits/Characters Tools
+### 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
@@ -157,7 +180,7 @@ Based on python `strftime()` behavior
 >>> JalaliDate(1367, 2, 14) == JalaliDate(datetime.date(1988, 5, 4))
 True
 
->>> JalaliDateTime(1367, 2, 14, 4, 30) >= JalaliDateTime(1369, 7, 1, 1, 0)
+>>> JalaliDateTime(1367, 2, 14, 4, 30) >= JalaliDateTime(1368, 2, 14, 1, 0)
 False
 
 >>> JalaliDate(1367, 2, 14) == datetime.date(1988, 5, 4)
@@ -170,21 +193,19 @@ JalaliDate(1395, 3, 21, Jomeh)
 datetime.timedelta(365)
 ```
 
-### Serializing and de-serializing
+### Serializing and Deserializing
 
 ```python
 >>> from persiantools.jdatetime import JalaliDate
 >>> import pickle
 
->>> # Serializing
->>> file = open("save.p", "wb")
->>> pickle.dump(JalaliDate(1367, 2, 14), file)
->>> file.close()
+# Serialize a Jalali date to a file
+>>> with open("save.p", "wb") as file:
+>>>     pickle.dump(JalaliDate(1367, 2, 14), file)
 
->>> # de-serializing
->>> file = open("save.p", "rb")
->>> jalali = pickle.load(file)
->>> file.close()
+# Deserialize from a file
+>>> with open("save.p", "rb") as file:
+>>>     jalali = pickle.load(file)
 >>> jalali
 JalaliDate(1367, 2, 14, Chaharshanbeh)
 ```

{persiantools-3.0.1 → persiantools-5.2.0}/README.md

@@ -7,72 +7,78 @@
 [![PyPI - Python Version](https://img.shields.io/pypi/pyversions/persiantools.svg)](https://pypi.org/project/persiantools/)
 [![PyPI - License](https://img.shields.io/pypi/l/persiantools.svg)](https://pypi.org/project/persiantools/)
 
-- Jalali (Shamsi) date and datetime (based on python datetime's module)
-
-  - Convert Jalali to Gregorian date/datetime and vice versa
-  - Support comparison and arithmetic operators such as `+`, `-`, `==`, `>=`
-  - Support timezone
-
-- Convert Arabic and Persian characters/digits to each other
-- Convert numbers to words
+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
 ```
-Persiantools supports Python 3.6+. (_for python 2.7 and 3.5 use [1.5.x](https://github.com/majiidd/persiantools/tree/1.5.x) version_)
 
-## How to use
+## Usage Guide
 
-### Date
+### Date Operations
 
 ```python
 >>> from persiantools.jdatetime import JalaliDate
 >>> import datetime
 
+# Get today's date in Jalali
 >>> JalaliDate.today()
-JalaliDate(1395, 4, 18, Jomeh)
+JalaliDate(1403, 8, 18, Jomeh)
 
->>> JalaliDate(1369, 7, 1)
-JalaliDate(1369, 7, 1, Yekshanbeh)
+>>> JalaliDate(1367, 2, 14)
+JalaliDate(1367, 2, 14, Chaharshanbeh)
 
->>> JalaliDate(datetime.date(1990, 9, 23))      # Gregorian to Jalali
-JalaliDate(1369, 7, 1, Yekshanbeh)
+# Convert Gregorian to Jalali
+>>> JalaliDate(datetime.date(1988, 5, 4))
+JalaliDate(1367, 2, 14, Chaharshanbeh)
 
->>> JalaliDate.to_jalali(2013, 9, 16)           # Gregorian to Jalali
+# Convert from Gregorian to Jalali using method
+>>> JalaliDate.to_jalali(2013, 9, 16)
 JalaliDate(1392, 6, 25, Doshanbeh)
 
->>> JalaliDate(1392, 6, 25).to_gregorian()      # Jalali to Gregorian
+# Convert from Jalali to Gregorian
+>>> JalaliDate(1392, 6, 25).to_gregorian()
 datetime.date(2013, 9, 16)
 
->>> JalaliDate.fromtimestamp(578707200)         # Timestamp to Jalali
+# Create a Jalali date from a Unix timestamp
+>>> JalaliDate.fromtimestamp(578707200)
 JalaliDate(1367, 2, 14, Chaharshanbeh)
 ```
 
-### Datetime
+### Datetime Operations
 
 ```python
 >>> from persiantools.jdatetime import JalaliDateTime
 >>> import datetime, pytz
 
+# Get the current Jalali datetime
 >>> JalaliDateTime.now()
-JalaliDateTime(1395, 4, 18, 1, 43, 24, 720505)
+JalaliDateTime(1403, 8, 18, 12, 48, 54, 569082)
 
->>> JalaliDateTime.now().to_gregorian()                                     # Jalali to Gregorian
-datetime.datetime(2016, 7, 8, 1, 43, 24, 720505)
+# Convert Jalali datetime to Gregorian
+>>> JalaliDateTime.now().to_gregorian()
+datetime.datetime(2024, 11, 8, 12, 48, 54, 569082)
 
->>> JalaliDateTime.to_jalali(datetime.datetime(1988, 5, 4, 14, 0, 0, 0))    # Gregorian to Jalali
+# Convert Gregorian datetime to Jalali
+>>> JalaliDateTime.to_jalali(datetime.datetime(1988, 5, 4, 14, 0, 0, 0))
 JalaliDateTime(1367, 2, 14, 14, 0)
 
->>> JalaliDateTime.fromtimestamp(578723400, pytz.timezone("Asia/Tehran"))   # Timestamp to Jalali
+# 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>)
 ```
 
-### Format
+### Formatting
 
 Based on python `strftime()` behavior
 
@@ -80,45 +86,50 @@ Based on python `strftime()` behavior
 >>> 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'
-
->>> JalaliDateTime.now(pytz.utc).strftime("%I:%M:%S.%f %p %z %Z")
-'01:49:22.518523 PM +0000 UTC'
 ```
 
-### Digits/Characters Tools
+### 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
@@ -126,7 +137,7 @@ Based on python `strftime()` behavior
 >>> JalaliDate(1367, 2, 14) == JalaliDate(datetime.date(1988, 5, 4))
 True
 
->>> JalaliDateTime(1367, 2, 14, 4, 30) >= JalaliDateTime(1369, 7, 1, 1, 0)
+>>> JalaliDateTime(1367, 2, 14, 4, 30) >= JalaliDateTime(1368, 2, 14, 1, 0)
 False
 
 >>> JalaliDate(1367, 2, 14) == datetime.date(1988, 5, 4)
@@ -139,21 +150,19 @@ JalaliDate(1395, 3, 21, Jomeh)
 datetime.timedelta(365)
 ```
 
-### Serializing and de-serializing
+### Serializing and Deserializing
 
 ```python
 >>> from persiantools.jdatetime import JalaliDate
 >>> import pickle
 
->>> # Serializing
->>> file = open("save.p", "wb")
->>> pickle.dump(JalaliDate(1367, 2, 14), file)
->>> file.close()
+# Serialize a Jalali date to a file
+>>> with open("save.p", "wb") as file:
+>>>     pickle.dump(JalaliDate(1367, 2, 14), file)
 
->>> # de-serializing
->>> file = open("save.p", "rb")
->>> jalali = pickle.load(file)
->>> file.close()
+# Deserialize from a file
+>>> with open("save.p", "rb") as file:
+>>>     jalali = pickle.load(file)
 >>> jalali
 JalaliDate(1367, 2, 14, Chaharshanbeh)
 ```

{persiantools-3.0.1 → persiantools-5.2.0}/persiantools/__init__.py

@@ -7,9 +7,9 @@
 
 __title__ = "persiantools"
 __url__ = "https://github.com/majiidd/persiantools"
-__version__ = "3.0.1"
+__version__ = "5.2.0"
 __build__ = __version__
 __author__ = "Majid Hajiloo"
 __author_email__ = "majid.hajiloo@gmail.com"
 __license__ = "MIT"
-__copyright__ = "Copyright (c) 2016-2022 Majid Hajiloo"
+__copyright__ = "Copyright (c) 2016-2025 Majid Hajiloo"

persiantools-5.2.0/persiantools/characters.py

@@ -0,0 +1,64 @@
+import re
+
+CHARACTER_MAP_AR_TO_FA = {
+    "دِ": "د",
+    "بِ": "ب",
+    "زِ": "ز",
+    "ذِ": "ذ",
+    "شِ": "ش",
+    "سِ": "س",
+    "ى": "ی",
+    "ي": "ی",
+    "ك": "ک",
+}
+
+CHARACTER_MAP_FA_TO_AR = {"ی": "ي", "ک": "ك"}
+
+AR_TO_FA_PATTERN = re.compile("|".join(map(re.escape, CHARACTER_MAP_AR_TO_FA.keys())))
+FA_TO_AR_PATTERN = re.compile("|".join(map(re.escape, CHARACTER_MAP_FA_TO_AR.keys())))
+
+
+def ar_to_fa(string: str) -> str:
+    """
+    Convert Arabic characters to Persian.
+
+    Usage::
+        from persiantools import characters
+        converted = characters.ar_to_fa("السلام عليكم")
+
+    Args:
+    string (str): The string to convert.
+
+    Returns:
+    str: The converted string with Arabic characters replaced by Persian characters.
+
+    Raises:
+    TypeError: If the input string is not of type str.
+    """
+    if not isinstance(string, str):
+        raise TypeError("Input must be of type str")
+
+    return AR_TO_FA_PATTERN.sub(lambda match: CHARACTER_MAP_AR_TO_FA[match.group(0)], string)
+
+
+def fa_to_ar(string: str) -> str:
+    """
+    Convert Persian characters to Arabic.
+
+    Usage::
+        from persiantools import characters
+        converted = characters.fa_to_ar("ای چرخ فلک خرابی از کینه تست")
+
+    Args:
+    string (str): The string to convert.
+
+    Returns:
+    str: The converted string with Persian characters replaced by Arabic characters.
+
+    Raises:
+    TypeError: If the input string is not of type str.
+    """
+    if not isinstance(string, str):
+        raise TypeError("Input must be of type str")
+
+    return FA_TO_AR_PATTERN.sub(lambda match: CHARACTER_MAP_FA_TO_AR[match.group(0)], string)