Django Jalali
=============
This module gives you a DateField same as Django’s DateField but you can
get and query data based on Jalali Date
Status
------
.. image:: https://github.com/slashmili/django-jalali/workflows/Tests/badge.svg?branch=main
:target: https://github.com/slashmili/django-jalali/actions
.. image:: https://img.shields.io/pypi/v/django_jalali.svg
:target: https://pypi.python.org/pypi/django_jalali
.. image:: https://img.shields.io/pypi/pyversions/django-jalali.svg
:target: https://pypi.org/project/django_jalali
.. image:: https://img.shields.io/pypi/djversions/django-jalali.svg
:target: https://pypi.org/project/django-jalali/
Dependencies
------------
- jdatetime_
- Django_ > 4.2
Looking for Django 1.X support? Checkout *2.4.6* version in pypi.org
- `Django REST Framework`_ > 3.12 (If install with ``drf`` dependency)
Supported Databases
-------------------
- SQLite
- PostgreSQL
Install
-------
.. code:: bash
pip install django_jalali
To use DRF serializer field:
.. code:: bash
pip install django_jalali[drf]
Usage
-----
1. Run :
.. code:: bash
$ django-admin startproject jalali_test
2. Start your app :
.. code:: bash
$ python manage.py startapp foo
3. Edit your Django project's ``settings.py`` file to include ``django_jalali`` and your application in the ``INSTALLED_APPS`` list. Make sure that ``django_jalali`` is listed **before** your apps for proper functionality.
Additionally, you can configure library settings using the ``JALALI_SETTINGS`` dictionary. If a setting is not explicitly defined, the default values will be used.
.. code-block:: python
# settings.py
INSTALLED_APPS = [
"django.contrib.admin",
"django.contrib.auth",
"django.contrib.contenttypes",
"django.contrib.sessions",
"django.contrib.messages",
"django.contrib.staticfiles",
"django_jalali", # Place this before your custom apps
]
JALALI_SETTINGS = {
# JavaScript static files for the admin Jalali date widget
"ADMIN_JS_STATIC_FILES": [
"admin/jquery.ui.datepicker.jalali/scripts/jquery-1.10.2.min.js",
"admin/jquery.ui.datepicker.jalali/scripts/jquery.ui.core.js",
"admin/jquery.ui.datepicker.jalali/scripts/jquery.ui.datepicker-cc.js",
"admin/jquery.ui.datepicker.jalali/scripts/calendar.js",
"admin/jquery.ui.datepicker.jalali/scripts/jquery.ui.datepicker-cc-fa.js",
"admin/main.js",
],
# CSS static files for the admin Jalali date widget
"ADMIN_CSS_STATIC_FILES": {
"all": [
"admin/jquery.ui.datepicker.jalali/themes/base/jquery-ui.min.css",
"admin/css/main.css",
]
},
}
4. Edit foo/models.py_
.. code:: python
from django.db import models
from django_jalali.db import models as jmodels
class Bar(models.Model):
objects = jmodels.jManager()
name = models.CharField(max_length=200)
date = jmodels.jDateField()
def __str__(self):
return "%s, %s" % (self.name, self.date)
class BarTime(models.Model):
objects = jmodels.jManager()
name = models.CharField(max_length=200)
datetime = jmodels.jDateTimeField()
def __str__(self):
return "%s, %s" % (self.name, self.datetime)
5. Run
.. code:: bash
$ python manage.py makemigrations
Migrations for 'foo':
foo/migrations/0001_initial.py:
- Create model Bar
- Create model BarTime
$ python manage.py migrate
Running migrations:
Applying foo.0001_initial... OK
6. Test it
.. code:: shell
$ python manage.py shell
Python 3.8.18 (default, Nov 26 2018, 15:26:54)
[GCC 6.3.0 20170516] on linux
Type "help", "copyright", "credits" or "license" for more information.
(InteractiveConsole)
>>> from foo.models import Bar
>>> import jdatetime
>>> today = jdatetime.date(1390, 5, 12)
>>> mybar = Bar(name="foo", date=today)
>>> mybar.save()
>>> mybar.date
jdatetime.date(1390, 5, 12)
>>> Bar.objects.filter(date=today)
[<Bar: foo, 1390-05-12>]
>>> Bar.objects.filter(date__gte="1390-5-12")
[<Bar: foo, 1390-05-12>]
>>> Bar.objects.filter(date='1363-8-01')
[]
>>> from foo.models import BarTime
>>> BarTime(name="Bar Time now", datetime=jdatetime.datetime(1380,8,2,12,12,12)).save()
>>> BarTime.objects.filter(datetime__date=jdatetime.datetime(1380,8,2,12,12,12))
[<BarTime: Bar Time now, 1380-08-0212:12:12>]
>>> BarTime.objects.filter(datetime__date=jdatetime.date(1380,8,2))
[<BarTime: Bar Time now, 1380-08-0212:12:12>]
>>> BarTime.objects.filter(datetime__date="1380-08-02")
[<BarTime: Bar Time now, 1380-08-0212:12:12>]
>>> BarTime.objects.filter(datetime__lt=jdatetime.datetime(1380,8,2,12,12,12))
[]
>>> BarTime.objects.filter(datetime__lte=jdatetime.datetime(1380,8,2,12,12,12))
[<BarTime: Bar Time now, 1380-08-0212:12:12>]
>>> BarTime.objects.filter(datetime__gt='1380-08-02')
[<BarTime: Bar Time now, 1380-08-0212:12:12>]
>>> BarTime.objects.filter(datetime__gt=d)
[]
>>> BarTime.objects.filter(datetime__year=1380)
[<BarTime: Bar Time now, 1380-08-0212:12:12>]
⚠️ `__month` filter is not supported as explained in here_
Using Templatetags
------------------
1. You can use ``jformat`` filter to format your dates in templates:
.. code:: python
{% load jformat %}
{{ my_date|jformat }} {# default formatting #}
{{ my_date|jformat:"%A %d %B %Y %H:%M" }} {# specific formatting #}
Admin Interface
---------------
1. Create foo/admin.py_
.. code:: python
from foo.models import Bar, BarTime
from django.contrib import admin
from django_jalali.admin.filters import JDateFieldListFilter
# You need to import this for adding jalali calendar widget
import django_jalali.admin as jadmin
class BarAdmin(admin.ModelAdmin):
list_filter = (
('date', JDateFieldListFilter),
)
admin.site.register(Bar, BarAdmin)
class BarTimeAdmin(admin.ModelAdmin):
list_filter = (
('datetime', JDateFieldListFilter),
)
admin.site.register(BarTime, BarTimeAdmin)
2. Config admin interface and fire up your django and enjoy using jalali date !
Django rest framework
---------------------
There are serializer fields corresponding to ``jmodels.JDateField`` and ``jmodels.JDateTimeField`` for DRF:
.. code:: python
from django_jalali.serializers.serializerfield import JDateField, JDateTimeField
from rest_framework.serializers import ModelSerializer
from foo.models import Bar, BarTime
class JDateFieldSerialializer(ModelSerializer):
date = JDateField()
class Meta:
model = Bar
exclude = []
class JDateTimeFieldSerializer(ModelSerializer):
datetime = JDateTimeField()
class Meta:
model = BarTime
exclude = []
Locale
------
In order to get the date string in farsi you need to set the locale to fa_IR
There are two ways to do achieve that, you can use of the approaches based on your needs
* Run server with LC_ALL env:
.. code:: shell
$ LC_ALL=fa_IR python manage.py runserver
* Set the locale in settings.py
.. code:: python
LANGUAGE_CODE = 'fa-ir'
import locale
locale.setlocale(locale.LC_ALL, "fa_IR.UTF-8")
* If using Docker, add the following to your Dockerfile:
.. code:: dockerfile
FROM python:3.11-slim-bookworm
RUN apt-get update && apt-get -y install locales && \
sed -i -e 's/# fa_IR UTF-8/fa_IR UTF-8/' /etc/locale.gen && \
dpkg-reconfigure --frontend=noninteractive locales
Timezone Settings
-----------------
From *django_jalali* version 3 and *Django* 2 you can use ``TIME_ZONE`` and ``USE_TZ`` settings_ to save datetime with project timezone
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 git@github.com:<you>/django-jalali.git
Initialize a virtual environment for development purposes:
.. code:: shell
$ python -m venv django_jalali_env
$ source ~/django_jalali_env/bin/activate
Then install the necessary requirements:
.. code:: shell
$ cd django-jalali
$ pip install -r requirements-test.txt
Unit tests are located in the ``tests`` folder and can be easily run with the pytest tool:
.. code:: shell
$ pytest
Before committing, you can run all the above tests against all supported Python and Django 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 environment(s), you can parametrize the tox run:
.. code:: shell
$ tox -e py39-django42
To add a new value to the Jalali settings, just add its default value to the ``DEFAULTS`` dictionary located in ``django_jalali/setting.py``.
You can access the new setting in your code as shown below:
.. code-block:: python
from django_jalali.settings import jalali_settings
custom_settings = jalali_settings.CUSTOM_SETTINGS
.. _jdatetime: https://github.com/slashmili/python-jalali
.. _Django: https://www.djangoproject.com/
.. _settings.py: https://github.com/slashmili/django-jalali/blob/master/jalali_test/jalali_test/settings.py#L40
.. _models.py: https://github.com/slashmili/django-jalali/blob/master/jalali_test/foo/models.py
.. _admin.py: https://github.com/slashmili/django-jalali/blob/master/jalali_test/foo/admin.py
.. _settings: https://github.com/slashmili/django-jalali/blob/master/jalali_test/jalali_test/settings.py#L116
.. _Django REST Framework: https://www.django-rest-framework.org/
.. _fork: https://help.github.com/en/articles/fork-a-repo
.. _repository: https://github.com/slashmili/django-jalali
.. _here: https://github.com/slashmili/django-jalali/issues/142#issuecomment-887464050
Raw data
{
"_id": null,
"home_page": "http://github.com/slashmili/django-jalali",
"name": "django-jalali",
"maintainer": null,
"docs_url": null,
"requires_python": null,
"maintainer_email": null,
"keywords": "django jalali",
"author": "Milad Rastian",
"author_email": "eslashmili@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/fb/a5/e8f04fb7bee039d2beab68ebfc19282fda657b57942e83b97db3904d566a/django_jalali-7.3.0.tar.gz",
"platform": "any",
"description": "Django Jalali\n=============\n\nThis module gives you a DateField same as Django\u2019s DateField but you can\nget and query data based on Jalali Date\n\nStatus\n------\n\n.. image:: https://github.com/slashmili/django-jalali/workflows/Tests/badge.svg?branch=main\n :target: https://github.com/slashmili/django-jalali/actions\n\n.. image:: https://img.shields.io/pypi/v/django_jalali.svg\n :target: https://pypi.python.org/pypi/django_jalali\n\n.. image:: https://img.shields.io/pypi/pyversions/django-jalali.svg\n :target: https://pypi.org/project/django_jalali\n\n.. image:: https://img.shields.io/pypi/djversions/django-jalali.svg\n :target: https://pypi.org/project/django-jalali/\n\nDependencies\n------------\n\n- jdatetime_\n- Django_ > 4.2\n\n Looking for Django 1.X support? Checkout *2.4.6* version in pypi.org\n- `Django REST Framework`_ > 3.12 (If install with ``drf`` dependency)\n\nSupported Databases\n-------------------\n\n- SQLite\n- PostgreSQL\n\nInstall\n-------\n.. code:: bash\n\n pip install django_jalali\n\nTo use DRF serializer field:\n\n.. code:: bash\n\n pip install django_jalali[drf]\n\nUsage\n-----\n\n1. Run :\n\n.. code:: bash\n\n $ django-admin startproject jalali_test\n\n2. Start your app :\n\n.. code:: bash\n\n $ python manage.py startapp foo\n\n3. Edit your Django project's ``settings.py`` file to include ``django_jalali`` and your application in the ``INSTALLED_APPS`` list. Make sure that ``django_jalali`` is listed **before** your apps for proper functionality.\n\n Additionally, you can configure library settings using the ``JALALI_SETTINGS`` dictionary. If a setting is not explicitly defined, the default values will be used.\n\n .. code-block:: python\n\n # settings.py\n INSTALLED_APPS = [\n \"django.contrib.admin\",\n \"django.contrib.auth\",\n \"django.contrib.contenttypes\",\n \"django.contrib.sessions\",\n \"django.contrib.messages\",\n \"django.contrib.staticfiles\",\n \"django_jalali\", # Place this before your custom apps\n ]\n\n JALALI_SETTINGS = {\n # JavaScript static files for the admin Jalali date widget\n \"ADMIN_JS_STATIC_FILES\": [\n \"admin/jquery.ui.datepicker.jalali/scripts/jquery-1.10.2.min.js\",\n \"admin/jquery.ui.datepicker.jalali/scripts/jquery.ui.core.js\",\n \"admin/jquery.ui.datepicker.jalali/scripts/jquery.ui.datepicker-cc.js\",\n \"admin/jquery.ui.datepicker.jalali/scripts/calendar.js\",\n \"admin/jquery.ui.datepicker.jalali/scripts/jquery.ui.datepicker-cc-fa.js\",\n \"admin/main.js\",\n ],\n # CSS static files for the admin Jalali date widget\n \"ADMIN_CSS_STATIC_FILES\": {\n \"all\": [\n \"admin/jquery.ui.datepicker.jalali/themes/base/jquery-ui.min.css\",\n \"admin/css/main.css\",\n ]\n },\n }\n\n4. Edit foo/models.py_\n\n.. code:: python\n\n from django.db import models\n from django_jalali.db import models as jmodels\n\n\n class Bar(models.Model):\n objects = jmodels.jManager()\n name = models.CharField(max_length=200)\n date = jmodels.jDateField()\n\n def __str__(self):\n return \"%s, %s\" % (self.name, self.date)\n\n\n class BarTime(models.Model):\n objects = jmodels.jManager()\n name = models.CharField(max_length=200)\n datetime = jmodels.jDateTimeField()\n\n def __str__(self):\n return \"%s, %s\" % (self.name, self.datetime)\n\n5. Run\n\n.. code:: bash\n\n $ python manage.py makemigrations\n Migrations for 'foo':\n foo/migrations/0001_initial.py:\n - Create model Bar\n - Create model BarTime\n $ python manage.py migrate\n Running migrations:\n Applying foo.0001_initial... OK\n\n6. Test it\n\n.. code:: shell\n\n $ python manage.py shell\n Python 3.8.18 (default, Nov 26 2018, 15:26:54)\n [GCC 6.3.0 20170516] on linux\n Type \"help\", \"copyright\", \"credits\" or \"license\" for more information.\n (InteractiveConsole)\n >>> from foo.models import Bar\n >>> import jdatetime\n >>> today = jdatetime.date(1390, 5, 12)\n >>> mybar = Bar(name=\"foo\", date=today)\n >>> mybar.save()\n >>> mybar.date\n jdatetime.date(1390, 5, 12)\n >>> Bar.objects.filter(date=today)\n [<Bar: foo, 1390-05-12>]\n >>> Bar.objects.filter(date__gte=\"1390-5-12\")\n [<Bar: foo, 1390-05-12>]\n >>> Bar.objects.filter(date='1363-8-01')\n []\n >>> from foo.models import BarTime\n >>> BarTime(name=\"Bar Time now\", datetime=jdatetime.datetime(1380,8,2,12,12,12)).save()\n >>> BarTime.objects.filter(datetime__date=jdatetime.datetime(1380,8,2,12,12,12))\n [<BarTime: Bar Time now, 1380-08-0212:12:12>]\n >>> BarTime.objects.filter(datetime__date=jdatetime.date(1380,8,2))\n [<BarTime: Bar Time now, 1380-08-0212:12:12>]\n >>> BarTime.objects.filter(datetime__date=\"1380-08-02\")\n [<BarTime: Bar Time now, 1380-08-0212:12:12>]\n >>> BarTime.objects.filter(datetime__lt=jdatetime.datetime(1380,8,2,12,12,12))\n []\n >>> BarTime.objects.filter(datetime__lte=jdatetime.datetime(1380,8,2,12,12,12))\n [<BarTime: Bar Time now, 1380-08-0212:12:12>]\n >>> BarTime.objects.filter(datetime__gt='1380-08-02')\n [<BarTime: Bar Time now, 1380-08-0212:12:12>]\n >>> BarTime.objects.filter(datetime__gt=d)\n []\n >>> BarTime.objects.filter(datetime__year=1380)\n [<BarTime: Bar Time now, 1380-08-0212:12:12>]\n\n\u26a0\ufe0f `__month` filter is not supported as explained in here_\n\nUsing Templatetags\n------------------\n\n1. You can use ``jformat`` filter to format your dates in templates:\n\n.. code:: python\n\n {% load jformat %}\n {{ my_date|jformat }} {# default formatting #}\n {{ my_date|jformat:\"%A %d %B %Y %H:%M\" }} {# specific formatting #}\n\nAdmin Interface\n---------------\n\n\n1. Create foo/admin.py_\n\n.. code:: python\n\n from foo.models import Bar, BarTime\n from django.contrib import admin\n\n from django_jalali.admin.filters import JDateFieldListFilter\n\n # You need to import this for adding jalali calendar widget\n import django_jalali.admin as jadmin\n\n\n class BarAdmin(admin.ModelAdmin):\n list_filter = (\n ('date', JDateFieldListFilter),\n )\n\n\n admin.site.register(Bar, BarAdmin)\n\n\n class BarTimeAdmin(admin.ModelAdmin):\n list_filter = (\n ('datetime', JDateFieldListFilter),\n )\n\n\n admin.site.register(BarTime, BarTimeAdmin)\n\n2. Config admin interface and fire up your django and enjoy using jalali date !\n\n\nDjango rest framework\n---------------------\n\nThere are serializer fields corresponding to ``jmodels.JDateField`` and ``jmodels.JDateTimeField`` for DRF:\n\n\n.. code:: python\n\n from django_jalali.serializers.serializerfield import JDateField, JDateTimeField\n from rest_framework.serializers import ModelSerializer\n\n from foo.models import Bar, BarTime\n\n\n class JDateFieldSerialializer(ModelSerializer):\n date = JDateField()\n\n class Meta:\n model = Bar\n exclude = []\n\n class JDateTimeFieldSerializer(ModelSerializer):\n datetime = JDateTimeField()\n\n class Meta:\n model = BarTime\n exclude = []\n\n\nLocale\n------\nIn order to get the date string in farsi you need to set the locale to fa_IR\n\nThere are two ways to do achieve that, you can use of the approaches based on your needs \n\n* Run server with LC_ALL env:\n\n.. code:: shell\n\n $ LC_ALL=fa_IR python manage.py runserver\n \n* Set the locale in settings.py\n\n.. code:: python\n\n LANGUAGE_CODE = 'fa-ir'\n import locale\n locale.setlocale(locale.LC_ALL, \"fa_IR.UTF-8\")\n\n* If using Docker, add the following to your Dockerfile:\n\n.. code:: dockerfile\n\n FROM python:3.11-slim-bookworm\n\n RUN apt-get update && apt-get -y install locales && \\\n sed -i -e 's/# fa_IR UTF-8/fa_IR UTF-8/' /etc/locale.gen && \\\n dpkg-reconfigure --frontend=noninteractive locales\n \n\nTimezone Settings\n-----------------\nFrom *django_jalali* version 3 and *Django* 2 you can use ``TIME_ZONE`` and ``USE_TZ`` settings_ to save datetime with project timezone\n\nDevelopment\n-----------\n\nYou can contribute to this project forking it from GitHub and sending pull requests.\n\nFirst fork_ the repository_ and then clone it:\n\n.. code:: shell\n\n $ git clone git@github.com:<you>/django-jalali.git\n\nInitialize a virtual environment for development purposes:\n\n.. code:: shell\n\n $ python -m venv django_jalali_env\n $ source ~/django_jalali_env/bin/activate\n\nThen install the necessary requirements:\n\n.. code:: shell\n\n $ cd django-jalali\n $ pip install -r requirements-test.txt\n\nUnit tests are located in the ``tests`` folder and can be easily run with the pytest tool:\n\n.. code:: shell\n\n $ pytest\n\nBefore committing, you can run all the above tests against all supported Python and Django versions with tox.\nYou need to install tox first:\n\n.. code:: shell\n\n $ pip install tox\n\nAnd then you can run all tests:\n\n.. code:: shell\n\n $ tox\n\nIf you wish to limit the testing to specific environment(s), you can parametrize the tox run:\n\n.. code:: shell\n\n $ tox -e py39-django42\n\nTo add a new value to the Jalali settings, just add its default value to the ``DEFAULTS`` dictionary located in ``django_jalali/setting.py``.\n\nYou can access the new setting in your code as shown below:\n\n.. code-block:: python\n\n from django_jalali.settings import jalali_settings\n\n custom_settings = jalali_settings.CUSTOM_SETTINGS\n\n.. _jdatetime: https://github.com/slashmili/python-jalali\n.. _Django: https://www.djangoproject.com/\n.. _settings.py: https://github.com/slashmili/django-jalali/blob/master/jalali_test/jalali_test/settings.py#L40\n.. _models.py: https://github.com/slashmili/django-jalali/blob/master/jalali_test/foo/models.py\n.. _admin.py: https://github.com/slashmili/django-jalali/blob/master/jalali_test/foo/admin.py\n.. _settings: https://github.com/slashmili/django-jalali/blob/master/jalali_test/jalali_test/settings.py#L116\n.. _Django REST Framework: https://www.django-rest-framework.org/\n.. _fork: https://help.github.com/en/articles/fork-a-repo\n.. _repository: https://github.com/slashmili/django-jalali\n.. _here: https://github.com/slashmili/django-jalali/issues/142#issuecomment-887464050\n",
"bugtrack_url": null,
"license": "Python Software Foundation License",
"summary": "Jalali Date support for Django model and admin interface",
"version": "7.3.0",
"project_urls": {
"Download": "http://github.com/slashmili/django-jalali/tarball/master",
"Homepage": "http://github.com/slashmili/django-jalali"
},
"split_keywords": [
"django",
"jalali"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "012ef8c08b1a87f02572b8a8922a0e2947f94dfa69d480b872cd024077ac9fba",
"md5": "5fc95866f4ba02e957b4ce13550c6ede",
"sha256": "ae8a45dd175e46cc6c394b837e85f4a7b126f80a0696efe21f07efd30d914156"
},
"downloads": -1,
"filename": "django_jalali-7.3.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "5fc95866f4ba02e957b4ce13550c6ede",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": null,
"size": 215443,
"upload_time": "2025-01-13T11:10:06",
"upload_time_iso_8601": "2025-01-13T11:10:06.610231Z",
"url": "https://files.pythonhosted.org/packages/01/2e/f8c08b1a87f02572b8a8922a0e2947f94dfa69d480b872cd024077ac9fba/django_jalali-7.3.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "fba5e8f04fb7bee039d2beab68ebfc19282fda657b57942e83b97db3904d566a",
"md5": "64429c8f0b079c194d79dcf129050bbd",
"sha256": "39e8d00e43fe5dfe11d3986fe13ccde8abd9ae6abbade523d1324ba14ecca729"
},
"downloads": -1,
"filename": "django_jalali-7.3.0.tar.gz",
"has_sig": false,
"md5_digest": "64429c8f0b079c194d79dcf129050bbd",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 204317,
"upload_time": "2025-01-13T11:10:08",
"upload_time_iso_8601": "2025-01-13T11:10:08.200038Z",
"url": "https://files.pythonhosted.org/packages/fb/a5/e8f04fb7bee039d2beab68ebfc19282fda657b57942e83b97db3904d566a/django_jalali-7.3.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-01-13 11:10:08",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "slashmili",
"github_project": "django-jalali",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"tox": true,
"lcname": "django-jalali"
}
JSON
