# JCVT
`JCVT` is a Python module for converting dates between the Gregorian and Jalali (Persian) calendars. This module also offers features for displaying Jalali dates as strings, showing day, month, and year separately, converting numbers to Persian, and determining the weekday.
## Features
- Supports various input formats, including date strings in multiple formats, `datetime.date` and `datetime.datetime` objects, tuples and lists, and Unix timestamps.
- Converts Gregorian dates to the Jalali calendar.
- Displays dates as strings or tuples.
- Shows the day, month, and year, as well as the month name, in Persian.
- Adds and subtracts days from a date.
- Calculates the day of the week and checks for leap years.
## Installation
To install, run the following command in the terminal:
```bash
pip install JCVT
```
## Usage
### Creating a JCVT Object
To create a `JCVT` object, you can pass various types of input as a date. Below are examples of supported input types:
```python
from jcvT import JCVT
import datetime
# Using different string formats
date1 = JCVT("2024-10-27")
date2 = JCVT("27-10-2024")
date3 = JCVT("10/27/2024")
# Using a datetime.date object
date4 = JCVT(datetime.date(2024, 10, 27))
# Using a datetime.datetime object
date5 = JCVT(datetime.datetime(2024, 10, 27, 12, 30))
# Using a tuple or list
date6 = JCVT((2024, 10, 27))
date7 = JCVT([2024, 10, 27])
# Using a Unix timestamp
date8 = JCVT(1730057449)
```
### Methods in JCVT
#### 1. `as_tuple(persian_numbers=False)`
This method 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)
```
#### 2. `as_string(sep="-", persian_numbers=False)`
This method returns the Jalali date as a string. `sep` specifies the separator between the year, month, and day (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)
```
#### 3. `as_verbose(persian_numbers=False)`
This method returns a descriptive string of the Jalali date, including the day, month name in Persian, and year. If `persian_numbers=True`, the numbers are displayed in Persian.
```python
jalali_verbose = date1.as_verbose()
jalali_verbose_persian = date1.as_verbose(persian_numbers=True)
```
#### 4. `to_gregorian(persian_numbers=False)`
This method returns the original Gregorian input date, useful for retrieving the initial input date. If `persian_numbers=True`, the numbers are displayed in Persian.
```python
gregorian_date = date1.to_gregorian()
gregorian_date_persian = date1.to_gregorian(persian_numbers=True)
```
#### 5. `get_day_of_week()`
This method returns the day of the week (e.g., "Monday", "Tuesday", etc.) for the input Gregorian date.
```python
day_of_week = date1.get_day_of_week()
```
#### 6. `is_leap_year()`
This method checks if the Jalali year is a leap year.
```python
is_leap = date1.is_leap_year()
```
#### 7. `add_days(days)`
This method returns a new date by adding a specified number of days to the current date.
```python
new_date = date1.add_days(10)
```
#### 8. `subtract_days(days)`
This method returns a new date by subtracting a specified number of days from the current date.
```python
new_date = date1.subtract_days(10)
```
#### 9. `get_day(persian_numbers=False)`
Returns the day 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)
```
#### 10. `get_month(persian_numbers=False)`
Returns the month 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)
```
#### 11. `get_year(persian_numbers=False)`
Returns the year 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)
```
### Examples
Below are some examples of using the methods in the `JCVT` module:
```python
# Convert date to Jalali string with "/" separator
print(date1.as_string(sep="/"))
# Display the Jalali date in verbose form
print(date1.as_verbose())
# Convert the Jalali date back to Gregorian
print(date1.to_gregorian())
# Add 15 days to the date
print(date1.add_days(15).as_string())
print(date1.add_days(15).as_string(persian_numbers=True, sep='/'))
# Get the day of the week
print(date1.get_day_of_week())
# Check if the year is a leap year
print(date1.is_leap_year())
```
## License
This project is licensed under the MIT License. For more details, refer to the `LICENSE` file.
Raw data
{
"_id": null,
"home_page": "https://github.com/eric-py/JCVT",
"name": "jcvt",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.6",
"maintainer_email": null,
"keywords": "jalali, gregorian, date, conversion, calendar",
"author": "Eric",
"author_email": "halakoei@yahoo.com",
"download_url": null,
"platform": null,
"description": "# JCVT\r\n\r\n`JCVT` is a Python module for converting dates between the Gregorian and Jalali (Persian) calendars. This module also offers features for displaying Jalali dates as strings, showing day, month, and year separately, converting numbers to Persian, and determining the weekday.\r\n\r\n## Features\r\n- Supports various input formats, including date strings in multiple formats, `datetime.date` and `datetime.datetime` objects, tuples and lists, and Unix timestamps.\r\n- Converts Gregorian dates to the Jalali calendar.\r\n- Displays dates as strings or tuples.\r\n- Shows the day, month, and year, as well as the month name, in Persian.\r\n- Adds and subtracts days from a date.\r\n- Calculates the day of the week and checks for leap years.\r\n\r\n## Installation\r\n\r\nTo install, run the following command in the terminal:\r\n\r\n```bash\r\npip install JCVT\r\n```\r\n\r\n## Usage\r\n\r\n### Creating a JCVT Object\r\n\r\nTo create a `JCVT` object, you can pass various types of input as a date. Below are examples of supported input types:\r\n\r\n```python\r\nfrom jcvT import JCVT\r\nimport datetime\r\n\r\n# Using different string formats\r\ndate1 = JCVT(\"2024-10-27\")\r\ndate2 = JCVT(\"27-10-2024\")\r\ndate3 = JCVT(\"10/27/2024\")\r\n\r\n# Using a datetime.date object\r\ndate4 = JCVT(datetime.date(2024, 10, 27))\r\n\r\n# Using a datetime.datetime object\r\ndate5 = JCVT(datetime.datetime(2024, 10, 27, 12, 30))\r\n\r\n# Using a tuple or list\r\ndate6 = JCVT((2024, 10, 27))\r\ndate7 = JCVT([2024, 10, 27])\r\n\r\n# Using a Unix timestamp\r\ndate8 = JCVT(1730057449)\r\n```\r\n\r\n### Methods in JCVT\r\n\r\n#### 1. `as_tuple(persian_numbers=False)`\r\n\r\nThis method returns 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#### 2. `as_string(sep=\"-\", persian_numbers=False)`\r\n\r\nThis method returns the Jalali date as a string. `sep` specifies the separator between the year, month, and day (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#### 3. `as_verbose(persian_numbers=False)`\r\n\r\nThis method returns a descriptive string of the Jalali date, including the day, month name in Persian, and year. If `persian_numbers=True`, the 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#### 4. `to_gregorian(persian_numbers=False)`\r\n\r\nThis method returns the original Gregorian input date, useful for retrieving the initial input date. If `persian_numbers=True`, the numbers are displayed in Persian.\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. `get_day_of_week()`\r\n\r\nThis method returns the day of the week (e.g., \"Monday\", \"Tuesday\", etc.) for the input Gregorian date.\r\n\r\n```python\r\nday_of_week = date1.get_day_of_week()\r\n```\r\n\r\n#### 6. `is_leap_year()`\r\n\r\nThis method checks 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#### 7. `add_days(days)`\r\n\r\nThis method returns a new date by adding a specified number of days to the current date.\r\n\r\n```python\r\nnew_date = date1.add_days(10)\r\n```\r\n\r\n#### 8. `subtract_days(days)`\r\n\r\nThis method returns a new date by subtracting a specified number of days from the current date.\r\n\r\n```python\r\nnew_date = date1.subtract_days(10)\r\n```\r\n\r\n#### 9. `get_day(persian_numbers=False)`\r\n\r\nReturns the day 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#### 10. `get_month(persian_numbers=False)`\r\n\r\nReturns the month 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#### 11. `get_year(persian_numbers=False)`\r\n\r\nReturns the year 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### Examples\r\n\r\nBelow are some examples of using the methods in the `JCVT` module:\r\n\r\n```python\r\n# Convert date to Jalali string with \"/\" separator\r\nprint(date1.as_string(sep=\"/\"))\r\n\r\n# Display the Jalali date in verbose form\r\nprint(date1.as_verbose())\r\n\r\n# Convert the Jalali date back to Gregorian\r\nprint(date1.to_gregorian())\r\n\r\n# Add 15 days to the date\r\nprint(date1.add_days(15).as_string())\r\nprint(date1.add_days(15).as_string(persian_numbers=True, sep='/'))\r\n\r\n# Get the day of the week\r\nprint(date1.get_day_of_week())\r\n\r\n# Check if the year is a leap year\r\nprint(date1.is_leap_year())\r\n```\r\n\r\n## License\r\n\r\nThis project is licensed under the MIT License. For more details, 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.1.0",
"project_urls": {
"Homepage": "https://github.com/eric-py/JCVT"
},
"split_keywords": [
"jalali",
" gregorian",
" date",
" conversion",
" calendar"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "e185569bdf44de8077d716dfe496a9da53783c302705fe87103e604ef3afda02",
"md5": "1b1b1233b8090b52f1de651cf1f3508e",
"sha256": "ef5bab8ab0b5dc72528f33a8ec39377bf79a1f1345df4e82425e0e366e1fd762"
},
"downloads": -1,
"filename": "jcvt-0.1.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "1b1b1233b8090b52f1de651cf1f3508e",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.6",
"size": 5831,
"upload_time": "2024-10-28T12:32:12",
"upload_time_iso_8601": "2024-10-28T12:32:12.997535Z",
"url": "https://files.pythonhosted.org/packages/e1/85/569bdf44de8077d716dfe496a9da53783c302705fe87103e604ef3afda02/jcvt-0.1.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-10-28 12:32:12",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "eric-py",
"github_project": "JCVT",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "jcvt"
}
JSON
