# D2J
`D2J (Date to Jalali)` is a Python module designed for converting dates between the Gregorian and Jalali (Persian) calendars. It offers a range of methods for displaying Jalali dates as strings, retrieving day, month, and year components individually, converting numbers to Persian, and determining the day of the week.
## Features
- **Supports various input types**: Including date strings in multiple formats, `datetime.date` and `datetime.datetime` objects, tuples, lists, and Unix timestamps.
- **Convert Gregorian to Jalali**: Direct conversion of Gregorian dates to Jalali dates.
- **Display as String or Tuple**: Option to display dates as custom strings or to retrieve day, month, and year separately.
- **Add or Subtract Days**: Easily add or subtract a specific number of days from a date.
- **Calculate Day of the Week and Leap Year**: Determine the day of the week and check if the Jalali year is a leap year.
- **New Features**: Includes `__str__`, `__repr__`, `now`, and `get_date` methods for enhanced display and retrieval of original input dates.
## Installation
To install this library, run the following command in your terminal:
```bash
pip install D2J
```
## Using the D2J Class
### Creating a D2J Object
To create a `D2J` object, you can pass various types of date inputs. These inputs include date strings in different formats, `datetime.date` object, Unix timestamp, and tuples or lists containing the year, month, and day.
Examples of creating a `D2J` object with different inputs:
```python
from d2j import D2J
import datetime
# Using various string formats
date1 = D2J("2024-10-27")
date2 = D2J("27-10-2024")
date3 = D2J("10/27/2024")
# Using a datetime.date object
date4 = D2J(datetime.date(2024, 10, 27))
# Using a datetime.datetime object
date5 = D2J(datetime.datetime(2024, 10, 27, 12, 30))
# Using a tuple or list
date6 = D2J((2024, 10, 27))
date7 = D2J([2024, 10, 27])
# Using a Unix timestamp
date8 = D2J(1730057449)
```
### Methods in the D2J Class
#### 1. `now()`
This class method returns a `D2J` object with the system’s current date.
```python
current_date = D2J.now()
```
#### 2. `__str__()` and `__repr__()`
These methods provide a string representation of the `D2J` object and return the Jalali date by default.
```python
print(date1) # Outputs the date as a string
repr(date1) # Shows the string representation with `repr`
```
#### 3. `get_date(sep="-", persian_numbers=False)`
Returns the original input date (Gregorian or Jalali) in its initial format. The `sep` parameter specifies the separator, and `persian_numbers` can be set to True to display numbers in Persian.
```python
input_date = date1.get_date()
input_date_persian = date1.get_date(persian_numbers=True)
```
#### 4. `to_gregorian(sep="-", persian_numbers=False)`
Converts the Jalali date to Gregorian and returns it as a string. If the input date was already Gregorian, it returns the original date unchanged.
```python
gregorian_date = date1.to_gregorian()
gregorian_date_persian = date1.to_gregorian(persian_numbers=True)
```
#### 5. `as_tuple(persian_numbers=False)`
Returns the Jalali date as a tuple `(year, month, day)`. If `persian_numbers=True`, the numbers are displayed in Persian.
```python
jalali_tuple = date1.as_tuple()
jalali_tuple_persian = date1.as_tuple(persian_numbers=True)
```
#### 6. `as_string(sep="-", persian_numbers=False)`
Returns the Jalali date as a string. The `sep` parameter specifies the separator to use (default is `"-"`). If `persian_numbers=True`, the numbers are displayed in Persian.
```python
jalali_string = date1.as_string()
jalali_string_custom_sep = date1.as_string(sep="/")
jalali_string_persian = date1.as_string(persian_numbers=True)
```
#### 7. `as_verbose(persian_numbers=False)`
Returns the Jalali date as a verbose string, including the day, Persian month name, and year. If `persian_numbers=True`, numbers are displayed in Persian.
```python
jalali_verbose = date1.as_verbose()
jalali_verbose_persian = date1.as_verbose(persian_numbers=True)
```
#### 8. `get_day_of_week()`
Returns the name of the weekday for the Gregorian input date in Persian (e.g., "Monday" as "دوشنبه").
```python
day_of_week = date1.get_day_of_week()
```
#### 9. `is_leap_year()`
Checks if the Jalali year is a leap year.
```python
is_leap = date1.is_leap_year()
```
#### 10. `add_days(days)`
Adds the specified number of days to the current date and returns a new `D2J` object with the updated date.
```python
new_date = date1.add_days(10)
```
#### 11. `subtract_days(days)`
Subtracts the specified number of days from the current date and returns a new `D2J` object with the updated date.
```python
new_date = date1.subtract_days(10)
```
#### 12. `get_day(persian_numbers=False)`
Returns the day component of the Jalali date. If `persian_numbers=True`, the day is displayed in Persian.
```python
day = date1.get_day()
day_persian = date1.get_day(persian_numbers=True)
```
#### 13. `get_month(persian_numbers=False)`
Returns the month component of the Jalali date. If `persian_numbers=True`, the month is displayed in Persian.
```python
month = date1.get_month()
month_persian = date1.get_month(persian_numbers=True)
```
#### 14. `get_year(persian_numbers=False)`
Returns the year component of the Jalali date. If `persian_numbers=True`, the year is displayed in Persian.
```python
year = date1.get_year()
year_persian = date1.get_year(persian_numbers=True)
```
### Practical Examples
Here are a few examples to illustrate how to use various methods in the `D2J` module:
```python
# Creating an object with the current system date
current_date = D2J.now()
# Displaying the Jalali date as a string with "/" as the separator
print(current_date.as_string(sep="/"))
# Displaying the Jalali date in verbose form
print(current_date.as_verbose())
# Converting the Jalali date to Gregorian
print(current_date.to_gregorian())
# Adding 15 days to the date
print(current_date.add_days(15).as_string())
print(current_date.add_days(15).as_string(persian_numbers=True, sep='/'))
# Retrieving the weekday
print(current_date.get_day_of_week())
# Checking if the Jalali year is a leap year
print(current_date.is_leap_year())
```
---
## License
This project is licensed under the MIT License. For more details, please refer to the `LICENSE` file.
Raw data
{
"_id": null,
"home_page": "https://github.com/eric-py/D2J",
"name": "D2J",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.6",
"maintainer_email": null,
"keywords": "jalali, shamsi, gregorian, date, conversion, calendar",
"author": "Eric",
"author_email": null,
"download_url": "https://files.pythonhosted.org/packages/e5/87/1df90d63a67cd31e8bea27b10314766f3ca93df344e56355a7a1218df5ce/d2j-0.2.0.tar.gz",
"platform": null,
"description": "# D2J\r\n\r\n`D2J (Date to Jalali)` is a Python module designed for converting dates between the Gregorian and Jalali (Persian) calendars. It offers a range of methods for displaying Jalali dates as strings, retrieving day, month, and year components individually, converting numbers to Persian, and determining the day of the week.\r\n\r\n## Features\r\n\r\n- **Supports various input types**: Including date strings in multiple formats, `datetime.date` and `datetime.datetime` objects, tuples, lists, and Unix timestamps.\r\n- **Convert Gregorian to Jalali**: Direct conversion of Gregorian dates to Jalali dates.\r\n- **Display as String or Tuple**: Option to display dates as custom strings or to retrieve day, month, and year separately.\r\n- **Add or Subtract Days**: Easily add or subtract a specific number of days from a date.\r\n- **Calculate Day of the Week and Leap Year**: Determine the day of the week and check if the Jalali year is a leap year.\r\n- **New Features**: Includes `__str__`, `__repr__`, `now`, and `get_date` methods for enhanced display and retrieval of original input dates.\r\n\r\n## Installation\r\n\r\nTo install this library, run the following command in your terminal:\r\n\r\n```bash\r\npip install D2J\r\n```\r\n\r\n## Using the D2J Class\r\n\r\n### Creating a D2J Object\r\n\r\nTo create a `D2J` object, you can pass various types of date inputs. These inputs include date strings in different formats, `datetime.date` object, Unix timestamp, and tuples or lists containing the year, month, and day.\r\n\r\nExamples of creating a `D2J` object with different inputs:\r\n\r\n```python\r\nfrom d2j import D2J\r\nimport datetime\r\n\r\n# Using various string formats\r\ndate1 = D2J(\"2024-10-27\")\r\ndate2 = D2J(\"27-10-2024\")\r\ndate3 = D2J(\"10/27/2024\")\r\n\r\n# Using a datetime.date object\r\ndate4 = D2J(datetime.date(2024, 10, 27))\r\n\r\n# Using a datetime.datetime object\r\ndate5 = D2J(datetime.datetime(2024, 10, 27, 12, 30))\r\n\r\n# Using a tuple or list\r\ndate6 = D2J((2024, 10, 27))\r\ndate7 = D2J([2024, 10, 27])\r\n\r\n# Using a Unix timestamp\r\ndate8 = D2J(1730057449)\r\n```\r\n\r\n### Methods in the D2J Class\r\n\r\n#### 1. `now()`\r\nThis class method returns a `D2J` object with the system\u00e2\u20ac\u2122s current date.\r\n\r\n```python\r\ncurrent_date = D2J.now()\r\n```\r\n\r\n#### 2. `__str__()` and `__repr__()`\r\nThese methods provide a string representation of the `D2J` object and return the Jalali date by default.\r\n\r\n```python\r\nprint(date1) # Outputs the date as a string\r\nrepr(date1) # Shows the string representation with `repr`\r\n```\r\n\r\n#### 3. `get_date(sep=\"-\", persian_numbers=False)`\r\nReturns the original input date (Gregorian or Jalali) in its initial format. The `sep` parameter specifies the separator, and `persian_numbers` can be set to True to display numbers in Persian.\r\n\r\n```python\r\ninput_date = date1.get_date()\r\ninput_date_persian = date1.get_date(persian_numbers=True)\r\n```\r\n\r\n#### 4. `to_gregorian(sep=\"-\", persian_numbers=False)`\r\nConverts the Jalali date to Gregorian and returns it as a string. If the input date was already Gregorian, it returns the original date unchanged.\r\n\r\n```python\r\ngregorian_date = date1.to_gregorian()\r\ngregorian_date_persian = date1.to_gregorian(persian_numbers=True)\r\n```\r\n\r\n#### 5. `as_tuple(persian_numbers=False)`\r\nReturns the Jalali date as a tuple `(year, month, day)`. If `persian_numbers=True`, the numbers are displayed in Persian.\r\n\r\n```python\r\njalali_tuple = date1.as_tuple()\r\njalali_tuple_persian = date1.as_tuple(persian_numbers=True)\r\n```\r\n\r\n#### 6. `as_string(sep=\"-\", persian_numbers=False)`\r\nReturns the Jalali date as a string. The `sep` parameter specifies the separator to use (default is `\"-\"`). If `persian_numbers=True`, the numbers are displayed in Persian.\r\n\r\n```python\r\njalali_string = date1.as_string()\r\njalali_string_custom_sep = date1.as_string(sep=\"/\")\r\njalali_string_persian = date1.as_string(persian_numbers=True)\r\n```\r\n\r\n#### 7. `as_verbose(persian_numbers=False)`\r\nReturns the Jalali date as a verbose string, including the day, Persian month name, and year. If `persian_numbers=True`, numbers are displayed in Persian.\r\n\r\n```python\r\njalali_verbose = date1.as_verbose()\r\njalali_verbose_persian = date1.as_verbose(persian_numbers=True)\r\n```\r\n\r\n#### 8. `get_day_of_week()`\r\nReturns the name of the weekday for the Gregorian input date in Persian (e.g., \"Monday\" as \"\u00d8\u00af\u00d9\u02c6\u00d8\u00b4\u00d9\u2020\u00d8\u00a8\u00d9\u2021\").\r\n\r\n```python\r\nday_of_week = date1.get_day_of_week()\r\n```\r\n\r\n#### 9. `is_leap_year()`\r\nChecks if the Jalali year is a leap year.\r\n\r\n```python\r\nis_leap = date1.is_leap_year()\r\n```\r\n\r\n#### 10. `add_days(days)`\r\nAdds the specified number of days to the current date and returns a new `D2J` object with the updated date.\r\n\r\n```python\r\nnew_date = date1.add_days(10)\r\n```\r\n\r\n#### 11. `subtract_days(days)`\r\nSubtracts the specified number of days from the current date and returns a new `D2J` object with the updated date.\r\n\r\n```python\r\nnew_date = date1.subtract_days(10)\r\n```\r\n\r\n#### 12. `get_day(persian_numbers=False)`\r\nReturns the day component of the Jalali date. If `persian_numbers=True`, the day is displayed in Persian.\r\n\r\n```python\r\nday = date1.get_day()\r\nday_persian = date1.get_day(persian_numbers=True)\r\n```\r\n\r\n#### 13. `get_month(persian_numbers=False)`\r\nReturns the month component of the Jalali date. If `persian_numbers=True`, the month is displayed in Persian.\r\n\r\n```python\r\nmonth = date1.get_month()\r\nmonth_persian = date1.get_month(persian_numbers=True)\r\n```\r\n\r\n#### 14. `get_year(persian_numbers=False)`\r\nReturns the year component of the Jalali date. If `persian_numbers=True`, the year is displayed in Persian.\r\n\r\n```python\r\nyear = date1.get_year()\r\nyear_persian = date1.get_year(persian_numbers=True)\r\n```\r\n\r\n### Practical Examples\r\n\r\nHere are a few examples to illustrate how to use various methods in the `D2J` module:\r\n\r\n```python\r\n# Creating an object with the current system date\r\ncurrent_date = D2J.now()\r\n\r\n# Displaying the Jalali date as a string with \"/\" as the separator\r\nprint(current_date.as_string(sep=\"/\"))\r\n\r\n# Displaying the Jalali date in verbose form\r\nprint(current_date.as_verbose())\r\n\r\n# Converting the Jalali date to Gregorian\r\nprint(current_date.to_gregorian())\r\n\r\n# Adding 15 days to the date\r\nprint(current_date.add_days(15).as_string())\r\nprint(current_date.add_days(15).as_string(persian_numbers=True, sep='/'))\r\n\r\n# Retrieving the weekday\r\nprint(current_date.get_day_of_week())\r\n\r\n# Checking if the Jalali year is a leap year\r\nprint(current_date.is_leap_year())\r\n```\r\n\r\n---\r\n\r\n## License\r\n\r\nThis project is licensed under the MIT License. For more details, please refer to the `LICENSE` file.\r\n",
"bugtrack_url": null,
"license": null,
"summary": "A module for converting dates between Gregorian and Jalali calendars.",
"version": "0.2.0",
"project_urls": {
"Bug Tracker": "https://github.com/eric-py/D2J/issues",
"GitHub": "https://github.com/eric-py/D2J",
"Homepage": "https://github.com/eric-py/D2J"
},
"split_keywords": [
"jalali",
" shamsi",
" gregorian",
" date",
" conversion",
" calendar"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "be9c0accc2cc55f504532abbb55cb12f26446c5a0a824de9dd6b35453182dfbb",
"md5": "607b1ff3c2363155821c42e9f9de3c99",
"sha256": "c5a8d7ec60b506eb4430d5a30b25e291e13ca1857487bce8aa53123358dd9ea4"
},
"downloads": -1,
"filename": "D2J-0.2.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "607b1ff3c2363155821c42e9f9de3c99",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.6",
"size": 6591,
"upload_time": "2024-10-30T09:50:01",
"upload_time_iso_8601": "2024-10-30T09:50:01.663969Z",
"url": "https://files.pythonhosted.org/packages/be/9c/0accc2cc55f504532abbb55cb12f26446c5a0a824de9dd6b35453182dfbb/D2J-0.2.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "e5871df90d63a67cd31e8bea27b10314766f3ca93df344e56355a7a1218df5ce",
"md5": "5ff6d3ab90ec26f8373c9068bda51657",
"sha256": "dbb2d8a5cd79a80bdc6f7fd8f642d9126d7a6b8ac10554072a7c1d741dd6917d"
},
"downloads": -1,
"filename": "d2j-0.2.0.tar.gz",
"has_sig": false,
"md5_digest": "5ff6d3ab90ec26f8373c9068bda51657",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.6",
"size": 6567,
"upload_time": "2024-10-30T09:50:03",
"upload_time_iso_8601": "2024-10-30T09:50:03.522569Z",
"url": "https://files.pythonhosted.org/packages/e5/87/1df90d63a67cd31e8bea27b10314766f3ca93df344e56355a7a1218df5ce/d2j-0.2.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-10-30 09:50:03",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "eric-py",
"github_project": "D2J",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "d2j"
}
JSON
