https://github.com/slashmili/python-jalali

Jalali calendar binding for Python based on Python's datetime module
https://github.com/slashmili/python-jalali

Last synced: about 2 months ago
JSON representation

Jalali calendar binding for Python based on Python's datetime module

• Host: GitHub
• URL: https://github.com/slashmili/python-jalali
• Owner: slashmili
• License: other
• Created: 2011-05-02T08:07:18.000Z (over 13 years ago)
• Default Branch: main
• Last Pushed: 2024-04-07T21:05:50.000Z (6 months ago)
• Last Synced: 2024-07-18T16:42:07.612Z (2 months ago)
• Language: Python
• Homepage: http://pypi.python.org/pypi/jdatetime/
• Size: 251 KB
• Stars: 334
• Watchers: 11
• Forks: 46
• Open Issues: 2
• Metadata Files:
  • Readme: README
  • Changelog: CHANGELOG.md
  • License: LICENSE

Awesome Lists containing this project

README

        
jdatetime

=========

jdatetime is Jalali_ implementation of Python's datetime module

Status

------

.. image:: https://github.com/slashmili/python-jalali/workflows/Tests/badge.svg?branch=main

   :target: https://github.com/slashmili/python-jalali/actions

.. image:: https://ci.appveyor.com/api/projects/status/ge5rk703ydx649a6?svg=true

   :target: https://ci.appveyor.com/project/slashmili/python-jalali

.. image:: https://img.shields.io/pypi/v/jdatetime.svg

   :target: https://pypi.python.org/pypi/jdatetime

.. image:: https://img.shields.io/pypi/pyversions/jdatetime.svg

   :target: https://pypi.python.org/pypi/jdatetime

Install

-------

``pip install jdatetime``

Documents

---------

This module exactly follows Python Standard datetime module's methods http://docs.python.org/release/3.7.1/library/datetime.html

Also these methods are added to jdatetime.date and jdatetime.datetime :

.. code-block:: python

    fromgregorian(**kw)

        Convert gregorian to jalali and return jdatetime.date

        jdatetime.date.fromgregorian(day=X,month=X,year=X)

        jdatetime.date.fromgregorian(date=datetime.date)

        jdatetime.datetime.fromgregorian(datetime=datetime.datetime)

    togregorian(self)

        Convert current jalali date to gregorian and return datetime.date

    isleap(self)

        check if year is leap year

        algortim is based on http://en.wikipedia.org/wiki/Leap_year

Example

-------

.. code-block:: shell

    >>> import jdatetime

    >>> jdatetime.datetime.now()

    jdatetime.datetime(1394, 12, 4, 8, 37, 31, 855729)

    >>> jdatetime.date.today()

    jdatetime.date(1394, 12, 4)

Locale

------

In order to get the date string in farsi you need to set the locale to `jdatetime.FA_LOCALE`. The locale

could be specified explicitly upon instantiation of `date`/`datetime` instances, or by

setting a default locale.

Instance locales is *named argument only*:

.. code-block:: python

    import jdatetime

    fa_date = jdatetime.date(1397, 4, 23, locale=jdatetime.FA_LOCALE)

    fa_datetime = jdatetime.datetime(1397, 4, 23, 11, 40, 30, locale=jdatetime.FA_LOCALE)

`date` and `datetime` instances provide the method `aslocale()` to return a clone of the instance

with the same timestamp, in a different locale.

Default Locale

~~~~~~~~~~~~~~

It's possible to set the default locale, so all new instances created afterwards would use

the desired locale, unless explicitly specified otherwise.

.. code-block:: shell

    >>> import locale

    >>> import jdatetime

    >> jdatetime.datetime.now().strftime("%a, %d %b %Y %H:%M:%S")

    u'Wed, 08 Ord 1395 20:47:32'

    >>> locale.setlocale(locale.LC_ALL, jdatetime.FA_LOCALE)

    'fa_IR'

    >>> jdatetime.datetime.now().strftime("%a, %d %b %Y %H:%M:%S")

    u'\u0686\u0647\u0627\u0631\u0634\u0646\u0628\u0647, 08 \u0627\u0631\u062f\u06cc\u0628\u0647\u0634\u062a 1395 20:47:56'

If your requirements demand to support different locales withing the same process,

you could set the default locale per thread. New `date` and `datetime` instances

created in each thread, will use the specified locale by default.

This supports both Python threads, and greenlets.

.. code-block:: python

    import jdatetime

    jdatetime.set_locale(jdatetime.FA_LOCALE)

    jdatetime.datetime.now().strftime('%A %B')

    # u'\u062f\u0648\u0634\u0646\u0628\u0647 \u062e\u0631\u062f\u0627\u062f'

Development

-----------

You can contribute to this project forking it from GitHub and sending pull requests.

First fork_ the repository_ and then clone it:

.. code:: shell

    $ git clone [email protected]:/python-jalali.git

Before committing, you can run all the above tests against all supported Python versions with tox.

You need to install tox first:

.. code:: shell

    $ pip install tox

And then you can run all tests:

.. code:: shell

    $ tox

If you wish to limit the testing to specific Python version, you can parametrize the tox run:

.. code:: shell

    $ tox -e py39

Release Steps

~~~~~~~~~~~~~~

* Bump the version in ``setup.py`` and ``jdatetime/__init__.py``. We are using Semantic Versioning.

* Add release notes in CHANGELOG.md

* Commit and push the changes. Create a PR

* After the PR is merged, create a release with a tag name like `v`

* Github Action creates the package and deploys it to pypi.

.. _Jalali: http://en.wikipedia.org/wiki/Iranian_calendar

.. _fork: https://help.github.com/en/articles/fork-a-repo

.. _repository: https://github.com/slashmili/python-jalali