# django-utz
django-utz provides easy-to-use decorators that allow you easily retrieve/display datetime values in the request user's or a specific user's local timezone without needing to do manual timezone conversions for each user.
"utz" here means "user time zone". This django app provides decorators for the project's User model, regular django models and django rest framework model serializers.
## Installation
Install with pip:
```bash
pip install django-utz
```
## Setup
Add `django_utz` to your `INSTALLED_APPS` setting:
```python
INSTALLED_APPS = [
...,
'django_utz',
]
```
Add `django_utz.middleware.DjangoUTZMiddleware` to `MIDDLEWARE`
```python
MIDDLEWARE = [
...,
'django_utz.middleware.DjangoUTZMiddleware',
]
```
You can then import and use the required user model decorator
```python
from django.contrib.auth.models import AbstractUser
from django_utz.decorators import usermodel
@usermodel
class CustomUser(AbstractUser):
'''Project's user model'''
email = models.EmailField()
username = models.CharField(max_length=50)
timezone = models.CharField(max_length=20)
...
class UTZMeta:
timezone_field = "timezone"
```
## Decorators
django_utz comes bundled with three decorators:
- `usermodel`: The project's User model must be decorated with this decorator for django_utz to work.
- `model`: Regular django models can be decorated with this decorator so that datetime fields in the model can be accessed in request.user's or any specified user local timezone always.
- `modelserializer`: Django rest framework model serializers can be decorated with this decorator so that the serializer's model datetime fields will always be returned in request.user's or any specified user local timezone in API responses.
Configurations for each model are defined in a `UTZMeta` class just inside the model or model serializer class.
For instance;
```python
from django.db import models
from django_utz.decorators import model
@model
class Post(models.Model):
'''Post model'''
title = models.CharField(max_length=255)
content = models.TextField()
created_at = models.DateTimeField(auto_now_add=True)
updated_at = models.DateTimeField(auto_now=True)
...
class UTZMeta:
datetime_fields = ["created_at", "updated_at"]
use_related_user_timezone = True
related_user = "author"
```
The possible configurations for each decorator will be discussed in the next sections.
### The `usermodel` decorator
The `usermodel` decorator is used to decorate the project's User model. This decorator basically adds django_utz support to the project. It adds a property to the User model that returns the user's timezone info as a zoneinfo.ZoneInfo or pytz.tzinfo object. It also adds a method to the User model that converts a datetime object to the user's local timezone and returns a `utzdatetime` object.
Let's look at an example of how you would use the `usermodel` decorator:
Here we will use [django-timezone-field](https://github.com/mfogel/django-timezone-field/) to add a timezone field to our User model. You can use any field you want.
```bash
pip install django-timezone-field
```
In settings.py, add `timezone_field` to `INSTALLED_APPS`:
```python
INSTALLED_APPS = [
...,
'django_utz',
'timezone_field',
]
```
In models.py, let's create a User model and decorate it with the `usermodel` decorator:
```python
from django.db import models
from django.contrib.auth.models import AbstractBaseUser, PermissionsMixin
from django_utz.decorators import usermodel
from timezone_field import TimeZoneField
@usermodel
class CustomUser(AbstractBaseUser, PermissionsMixin):
'''User model'''
username = models.CharField(max_length=255, unique=True)
email = models.EmailField(max_length=255, unique=True)
timezone = TimeZoneField(default="UTC")
...
USERNAME_FIELD = "email"
REQUIRED_FIELDS = ["username"]
class Meta:
verbose_name = "Custom user"
verbose_name_plural = "Custom users"
class UTZMeta:
timezone_field = "timezone" # valid user timezone info field name
```
Simple right! Now let's look at the configurations for the `usermodel` decorator.
The only configuration for the `usermodel` decorator is the `timezone_field` attribute. This attribute is used to specify the field that contains the user timezone info or name, as seen in the example above.
The `usermodel` decorator adds a property and a method to the User model. It can be said these added property and method are the backbone of the `django_utz` module. Let's look at them:
- The `utz` property: This property returns the user's timezone info as a zoneinfo.ZoneInfo or pytz.tzinfo object, even if the user's timezone is stored as a string in the database.
The type of timezone info object returned depends mainly on the `USE_DEPRECATED_PYTZ` setting. If `USE_DEPRECATED_PYTZ` is set to `True`, the timezone info object returned will be a pytz.tzinfo object. Otherwise, the timezone info object returned will be a zoneinfo.ZoneInfo object.
- The `to_local_timezone` method: This method converts any datetime object passed to it to a `utzdatetime` object in the user's local timezone as returned by the `utz` property.
To see how these work, we can create a user instance and use the `utz` property and `to_local_timezone` method:
```python
from django.utils import timezone
my_user = CustomUser.objects.create_user(
username="Tolu",
email="testing321@gmail.com",
password="testing321",
timezone="Africa/Lagos"
)
# Getting the user's timezone info
user_timezone = my_user.utz
print(user_timezone) # Africa/Lagos
print(type(user_timezone)) # zoneinfo.ZoneInfo, assuming USE_DEPRECATED_PYTZ is set to False
# Converting a datetime object in server's timezone (UTC) to user's local timezone
now = timezone.now()
print(now) # 1996-12-19 16:39:57.000200+00:00
now_in_user_tz = my_user.to_local_timezone(now)
print(now_in_user_tz) # 1996-12-19 17:39:57.000200+01:00
```
In the above example, we can see that the current time in the user's timezone is one hour ahead of the current time in the server's timezone.
> Note that the `to_local_timezone` method returns a `utzdatetime` object. This is because the `utzdatetime` object is independent of settings.USE_TZ. This means that the `utzdatetime` object will always be in the user's timezone regardless of the value of settings.USE_TZ. Read more on the `utzdatetime` object [here](#the-utzdatetime-object).
### The `model` decorator
The `model` decorator is used to decorate regular django models. This decorator allows you to access model datetime fields in a user's local timezone. The user can be the request user or any specified user. By default, the request user is used.
Curious about how this works? To keep things simple, the decorator uses a kind of descriptor called the `FunctionAttribute` descriptor to add a new version of each datetime field to the model class. This new version of the datetime field is suffixed with "utz"(by default) and is a property that returns the datetime field in the user's local timezone.
Say for example, we have a model called `Post` and we want to access the `created_at` field in the request user's timezone.
```python
from django.db import models
from django_utz.decorators import model
@model
class Post(models.Model):
'''Post model'''
title = models.CharField(max_length=255)
content = models.TextField()
author = models.ForeignKey(CustomUser, on_delete=models.CASCADE)
created_at = models.DateTimeField(auto_now_add=True)
updated_at = models.DateTimeField(auto_now=True)
...
class UTZMeta:
datetime_fields = "__all__"
```
The decorator adds a new attribute to the `Post` model called `created_at_utz`. Let's create a post instance and see how this works:
```python
from django.contrib.auth import get_user_model
User = get_user_model()
tolu = User.objects.get(username="Tolu")
new_post = Post.objects.create(
title="New Post",
content="Lorem Ipsum",
author=tolu
)
# If the post was created at 12:00:00 UTC, it will be 13:00:00 in the user's timezone.
# Remember, Tolu's timezone is "Africa/Lagos"
print(new_post.created_at_utz) # 1996-12-19 13:00:00.000200+01:00
```
The `model` decorator has a few configurations one of which was used in the model definition above. The configurations are:
- `datetime_fields`: A list or tuple of the model's datetime fields for which user timezone aware fields should be added. If set to `"__all__"`, all datetime fields in the model will have user timezone aware fields added.
- `use_related_user_timezone`: An optional boolean value that determines if the user timezone aware fields should be based on the timezone of a directly related user, not the request user. This defaults to `False`.
The related user in the case of the `Post` model is the `post.author`. If a related user is not found directly in the model, django_utz tries to search for a user in the related models of the model. A related model is usually a model that is linked by a ForeignKey or OneToOneField to the current model.
To define explicitly the user whose timezone will be used, you can set this comfiguration to `True` and then defined the path to user on the `related_user` configuration.
- `related_user`: This is also an optional configuration that specifies the path to the user whose timezone will be used. This is only used when `use_related_user_timezone` is set to `True`. The path is a string that represents the path to the user from the model. The path is in the format `related_model.related_model....user_field`.
Looks complicated? Let's look at two examples:
**Example 1:**
Assume we want all datetime fields in the `Post` model to always be returned in the post author's timezone. We can do this:
```python
from django.db import models
from django_utz.decorators import model
@model
class Post(models.Model):
'''Post model'''
title = models.CharField(max_length=255)
content = models.TextField()
author = models.ForeignKey(CustomUser, on_delete=models.CASCADE)
created_at = models.DateTimeField(auto_now_add=True)
updated_at = models.DateTimeField(auto_now=True)
...
class UTZMeta:
datetime_fields = "__all__"
use_related_user_timezone = True
related_user = "author"
```
So no matter the user that makes the request, the datetime fields in the `Post` model will always be returned in the post author's timezone.
You could also decide to not specify the `related_user` configuration. django_utz will use the first user it finds in the related models of the model. Which is the `author` in this case.
**Example 2:**
Let's add a new model called `Comment` that is related to the `Post` model. However, we want all datetime fields in the `Comment` model to always be returned in the post author's timezone. We can do this:
```python
from django.db import models
from django_utz.decorators import model
@model
class Comment(models.Model):
'''Comment model'''
post = models.ForeignKey(Post, on_delete=models.CASCADE)
author = models.ForeignKey(CustomUser, on_delete=models.CASCADE)
content = models.TextField()
created_at = models.DateTimeField(auto_now_add=True)
updated_at = models.DateTimeField(auto_now=True)
...
class UTZMeta:
datetime_fields = "__all__"
use_related_user_timezone = True
related_user = "post.author"
```
In this case, the `related_user` configuration is set to `"post.author"`. This means that the datetime fields in the `Comment` model will always be returned in the post author's timezone, not the comment author's timezone (to be clear, the comment author is the user that made the comment).
Hence, Assuming 'Tolu' already created a new post called 'new_post' and we created a user called 'Tade' with a timezone of "Asia/Tokyo", we can do this:
```python
tade = User.objects.get(username="Tade")
comment = Comment.objects.create(
post=new_post,
author=tade,
content="Nice post!"
)
print(comment.created_at_utz) # 1996-12-19 13:00:00.000200+01:00 (Africa/Lagos)
print(comment.author.utz) # Asia/Tokyo
print(comment.author.to_local_timezone(comment.created_at)) # 1996-12-19 21:00:00.000200+09:00 (Asia/Tokyo)
```
- `attribute_suffix`: This is an optional configuration that specifies the suffix to be added to the user timezone aware fields. This defaults to "utz".
You may want to access created_at in the user's timezone as `created_at_local` instead of `created_at_utz`. You can do this:
```python
@model
class Post(models.Model):
'''Post model'''
...
class UTZMeta:
...
attribute_suffix = "local"
```
### The `modelserializer` decorator
This decorator is used to decorate django rest framework model serializers. As said at the beginning, this decorator allows you to always return the serializer's model datetime fields in the request user's local timezone or any specified user's local timezone(based on the configurations in the serializer's model) in API responses.
However, for the decorator to work, the serializer's model must have also been decorated with the `model` decorator.
Let's say we want to create a serializer for our model `Post`:
```python
from rest_framework import serializers
from django_utz.decorators import modelserializer
from my_app.models import Post
@modelserializer
class PostSerializer(serializers.ModelSerializer):
'''Post serializer'''
class Meta:
model = Post
fields = "__all__"
class UTZMeta:
auto_add_fields = True
```
The available configurations for the `modelserializer` decorator are:
- `auto_add_fields`: This is a boolean value that determines if the decorator should automatically add timezone aware serializer fields to the serializer. This defaults to `True`.
- `datetime_format`: This is an optional string that specifies the format to be used when serializing the datetime fields.
> If you need complete control over the serializer fields, you can set the `auto_add_fields` config to `False` or decide not to decorate the model serializer and then add the timezone aware serializer fields manually. Read more on timezone aware serializer fields [here](#serializer-fields).
Also, you do not need to worry about the serializers Meta configuration not been applied. The `modelserializer` decorator respects the Meta configuration of the serializer so all excluded fields, read_only fields, and extra keyword arguments etc will be respected.
## Fields
### Serializer Fields
In the case that you need complete control over the auto-added serializer fields, you can add user timezone aware serializer datetime fields manually.
- `UTZDateTimeField`: A serializer field that represents a timezone aware datetime field in the preferred user's local timezone (as defined in the serializer's model).
```python
from rest_framework import serializers
from django_utz.serializers_fields import UTZDateTimeField
class PostSerializer(serializers.ModelSerializer):
'''Post serializer'''
created_at = UTZDateTimeField(read_only=True, format="%Y-%m-%d %H:%M:%S %Z (%z)")
updated_at = UTZDateTimeField(read_only=True, label="Last updated at", format="%Y-%m-%d %H:%M:%S %Z (%z)")
class Meta:
model = Post
fields = "__all__"
```
## Signals
The `django_utz.signals` module contains signals that are sent when an event occurs on a user's timezone. The signals are:
- `user_timezone_changed`: Sent when a user's timezone is updated.
In your receiver, you can access the user object, its previous timezone and current timezone with the `instance`, `previous_timezone`and `current_timezone` keyword arguments respectively.
```python
from django.dispatch import receiver
from django_utz.signals import user_timezone_changed
@receiver(user_timezone_changed)
def user_timezone_changed_receiver(sender, **kwargs):
old_timezone = kwargs.get("previous_timezone")
new_timezone = kwargs.get("current_timezone")
print(old_timezone, new_timezone)
```
## Templates
### Template Tags
The `django_utz.templatetags.django_utz` module contains a template tag that allows you to display datetime objects in the preferred user's local timezone. To use in a template, load the module in your template:
```html
{% load django_utz %}
```
- `usertimezone`: This is a block tag that renders template content with datetime object(s) contained within the block in the request user's timezone but the preferred user can be passed as an argument or keyword argument. Assuming that we want to write a template for our post list view, we can do this:
Here the datetime objects, `post.created_at` is rendered in the request user's timezone:
```html
{% load django_utz %}
{% usertimezone %}
{% for post in posts %}
<h3>{{ post.title }}</h3>
<p>{{ post.created_at }}</p>
<p>{{ post.author }}</p>
{% endfor %}
{% endusertimezone %}
```
Say we want to render the datetime object, `post.created_at` in the timezone of the author of the first post, we can do this:
First approach:
```html
{% load django_utz %}
{% usertimezone posts[0].author %}
{% for post in posts %}
<h3>{{ post.title }}</h3>
<p>{{ post.created_at }}</p>
<p>{{ post.author }}</p>
{% endfor %}
{% endusertimezone %}
```
Alternatively;
```html
{% load django_utz %}
{% usertimezone user=posts[0].author %}
{% for post in posts %}
<h3>{{ post.title }}</h3>
<p>{{ post.created_at }}</p>
<p>{{ post.author }}</p>
{% endfor %}
{% endusertimezone %}
```
### Template Filters
django_utz also provides a template filter that allows you to display datetime objects in the preferred user's local timezone.
- `usertimezone`: This filter returns a datetime object in the request user's timezone but the preferred user can be passed as an argument.
Say we want to write a template for our post detail view, we can do this:
```html
{% load django_utz %}
<h3>{{ post.title }}</h3>
<p>{{ post.content }}</p>
<p>{{ post.created_at|usertimezone }}</p>
<p>{{ post.author }}</p>
```
This works the same way as the `usertimezone` template tag.
We can also pass the preferred user as an argument:
```html
{% load utz %}
<h3>{{ post.title }}</h3>
<p>{{ post.content }}</p>
<p>{{ post.created_at|usertimezone:post.author }}</p>
<p>{{ post.author }}</p>
```
## The `utzdatetime` object
This is a custom datetime that can be independent of settings.USE_TZ. It inherits from `datetime.datetime`. The reason this exists is because when USE_TZ is set to True, sometimes, datetime objects are converted back to the server's timezone. This can be a problem when you want to view datetime objects in a timezone other than the server's timezone.
A peculiar case is in templates. If you try to access say, `post.created_at_utz` in a template, you'd get the datetime object in the server's timezone. This is because the datetime object is converted back to the server's timezone when USE_TZ is set to True. Hence, the reason why a `utzdatetime` is used.
This object is timezone aware and can be used to display datetime objects in any timezone.
> This concept was gotten from `django.templatetags.tz`'s `datetimeobject`.
The `utzdatetime` object has the following methods:
- `from_datetime(cls, _datetime: datetime.datetime)`: This class method allows the construction of a `utzdatetime` object from a datetime object.
```python
import datetime
from django_utz.datetime import utzdatetime
normal_datetime = datetime.datetime.now()
utz_datetime = utzdatetime.from_datetime(normal_datetime)
```
- `regard_usetz()`: This method makes the `utzdatetime` object respect settings.USE_TZ when being converted to a timezone. It may be converted back to server's timezone if USE_TZ is set to True.
```python
utz_datetime.regard_usetz()
# Now the utzdatetime object is dependent on settings.USE_TZ
```
- `disregard_usetz()`: This method makes the `utzdatetime` object disregard settings.USE_TZ when being converted to a timezone. It will not be converted back to server's timezone if USE_TZ is set to True.
```python
utz_datetime.disregard_usetz()
# Now the utzdatetime object is independent of settings.USE_TZ
```
**Contributions and feedbacks are welcome. For feedbacks, please open an issue. To contribute, please fork the repo and submit a pull request. Thanks!**
Raw data
{
"_id": null,
"home_page": "",
"name": "django-utz",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.7",
"maintainer_email": "\"Daniel T. Afolayan (ti-oluwa)\" <tioluwa.dev@gmail.com>",
"keywords": "User Timezone,Auto Timezone Conversion,Django Timezone",
"author": "",
"author_email": "\"Daniel T. Afolayan (ti-oluwa)\" <tioluwa.dev@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/14/07/ae0a6cac5029899bd93bb416765202de5e0c0fa1ab153377985ec80ea1d6/django_utz-0.1.9.tar.gz",
"platform": null,
"description": "# django-utz\r\n\r\ndjango-utz provides easy-to-use decorators that allow you easily retrieve/display datetime values in the request user's or a specific user's local timezone without needing to do manual timezone conversions for each user.\r\n\r\n\"utz\" here means \"user time zone\". This django app provides decorators for the project's User model, regular django models and django rest framework model serializers.\r\n\r\n## Installation\r\n\r\nInstall with pip:\r\n\r\n```bash\r\npip install django-utz\r\n```\r\n\r\n## Setup\r\n\r\nAdd `django_utz` to your `INSTALLED_APPS` setting:\r\n\r\n```python\r\nINSTALLED_APPS = [\r\n ...,\r\n 'django_utz',\r\n]\r\n```\r\n\r\nAdd `django_utz.middleware.DjangoUTZMiddleware` to `MIDDLEWARE`\r\n\r\n```python\r\nMIDDLEWARE = [\r\n ...,\r\n 'django_utz.middleware.DjangoUTZMiddleware',\r\n]\r\n```\r\n\r\nYou can then import and use the required user model decorator\r\n\r\n```python\r\nfrom django.contrib.auth.models import AbstractUser\r\n\r\nfrom django_utz.decorators import usermodel\r\n\r\n\r\n@usermodel\r\nclass CustomUser(AbstractUser):\r\n '''Project's user model'''\r\n email = models.EmailField()\r\n username = models.CharField(max_length=50)\r\n timezone = models.CharField(max_length=20)\r\n ...\r\n \r\n class UTZMeta:\r\n timezone_field = \"timezone\"\r\n```\r\n\r\n## Decorators\r\n\r\ndjango_utz comes bundled with three decorators:\r\n\r\n- `usermodel`: The project's User model must be decorated with this decorator for django_utz to work.\r\n- `model`: Regular django models can be decorated with this decorator so that datetime fields in the model can be accessed in request.user's or any specified user local timezone always.\r\n- `modelserializer`: Django rest framework model serializers can be decorated with this decorator so that the serializer's model datetime fields will always be returned in request.user's or any specified user local timezone in API responses.\r\n\r\nConfigurations for each model are defined in a `UTZMeta` class just inside the model or model serializer class.\r\n\r\nFor instance;\r\n\r\n```python\r\nfrom django.db import models\r\n\r\nfrom django_utz.decorators import model\r\n\r\n@model\r\nclass Post(models.Model):\r\n '''Post model'''\r\n title = models.CharField(max_length=255)\r\n content = models.TextField()\r\n created_at = models.DateTimeField(auto_now_add=True)\r\n updated_at = models.DateTimeField(auto_now=True)\r\n ...\r\n \r\n class UTZMeta:\r\n datetime_fields = [\"created_at\", \"updated_at\"]\r\n use_related_user_timezone = True\r\n related_user = \"author\"\r\n```\r\n\r\nThe possible configurations for each decorator will be discussed in the next sections.\r\n\r\n### The `usermodel` decorator\r\n\r\nThe `usermodel` decorator is used to decorate the project's User model. This decorator basically adds django_utz support to the project. It adds a property to the User model that returns the user's timezone info as a zoneinfo.ZoneInfo or pytz.tzinfo object. It also adds a method to the User model that converts a datetime object to the user's local timezone and returns a `utzdatetime` object.\r\n\r\nLet's look at an example of how you would use the `usermodel` decorator:\r\n\r\nHere we will use [django-timezone-field](https://github.com/mfogel/django-timezone-field/) to add a timezone field to our User model. You can use any field you want.\r\n\r\n```bash\r\npip install django-timezone-field\r\n```\r\n\r\nIn settings.py, add `timezone_field` to `INSTALLED_APPS`:\r\n\r\n```python\r\n\r\nINSTALLED_APPS = [\r\n ...,\r\n 'django_utz',\r\n 'timezone_field',\r\n]\r\n```\r\n\r\nIn models.py, let's create a User model and decorate it with the `usermodel` decorator:\r\n\r\n```python\r\nfrom django.db import models\r\nfrom django.contrib.auth.models import AbstractBaseUser, PermissionsMixin\r\n\r\nfrom django_utz.decorators import usermodel\r\nfrom timezone_field import TimeZoneField\r\n\r\n@usermodel\r\nclass CustomUser(AbstractBaseUser, PermissionsMixin):\r\n '''User model'''\r\n username = models.CharField(max_length=255, unique=True)\r\n email = models.EmailField(max_length=255, unique=True)\r\n timezone = TimeZoneField(default=\"UTC\")\r\n ...\r\n\r\n USERNAME_FIELD = \"email\"\r\n REQUIRED_FIELDS = [\"username\"]\r\n\r\n class Meta:\r\n verbose_name = \"Custom user\"\r\n verbose_name_plural = \"Custom users\"\r\n\r\n class UTZMeta:\r\n timezone_field = \"timezone\" # valid user timezone info field name\r\n```\r\n\r\nSimple right! Now let's look at the configurations for the `usermodel` decorator.\r\n\r\nThe only configuration for the `usermodel` decorator is the `timezone_field` attribute. This attribute is used to specify the field that contains the user timezone info or name, as seen in the example above.\r\n\r\nThe `usermodel` decorator adds a property and a method to the User model. It can be said these added property and method are the backbone of the `django_utz` module. Let's look at them:\r\n\r\n- The `utz` property: This property returns the user's timezone info as a zoneinfo.ZoneInfo or pytz.tzinfo object, even if the user's timezone is stored as a string in the database. \r\n\r\nThe type of timezone info object returned depends mainly on the `USE_DEPRECATED_PYTZ` setting. If `USE_DEPRECATED_PYTZ` is set to `True`, the timezone info object returned will be a pytz.tzinfo object. Otherwise, the timezone info object returned will be a zoneinfo.ZoneInfo object.\r\n\r\n- The `to_local_timezone` method: This method converts any datetime object passed to it to a `utzdatetime` object in the user's local timezone as returned by the `utz` property.\r\n\r\nTo see how these work, we can create a user instance and use the `utz` property and `to_local_timezone` method:\r\n\r\n```python\r\nfrom django.utils import timezone\r\n\r\nmy_user = CustomUser.objects.create_user(\r\n username=\"Tolu\",\r\n email=\"testing321@gmail.com\",\r\n password=\"testing321\",\r\n timezone=\"Africa/Lagos\"\r\n)\r\n\r\n# Getting the user's timezone info\r\nuser_timezone = my_user.utz\r\nprint(user_timezone) # Africa/Lagos\r\nprint(type(user_timezone)) # zoneinfo.ZoneInfo, assuming USE_DEPRECATED_PYTZ is set to False\r\n\r\n# Converting a datetime object in server's timezone (UTC) to user's local timezone\r\nnow = timezone.now()\r\nprint(now) # 1996-12-19 16:39:57.000200+00:00\r\nnow_in_user_tz = my_user.to_local_timezone(now)\r\nprint(now_in_user_tz) # 1996-12-19 17:39:57.000200+01:00\r\n```\r\n\r\nIn the above example, we can see that the current time in the user's timezone is one hour ahead of the current time in the server's timezone.\r\n\r\n> Note that the `to_local_timezone` method returns a `utzdatetime` object. This is because the `utzdatetime` object is independent of settings.USE_TZ. This means that the `utzdatetime` object will always be in the user's timezone regardless of the value of settings.USE_TZ. Read more on the `utzdatetime` object [here](#the-utzdatetime-object).\r\n\r\n### The `model` decorator\r\n\r\nThe `model` decorator is used to decorate regular django models. This decorator allows you to access model datetime fields in a user's local timezone. The user can be the request user or any specified user. By default, the request user is used.\r\n\r\nCurious about how this works? To keep things simple, the decorator uses a kind of descriptor called the `FunctionAttribute` descriptor to add a new version of each datetime field to the model class. This new version of the datetime field is suffixed with \"utz\"(by default) and is a property that returns the datetime field in the user's local timezone.\r\n\r\nSay for example, we have a model called `Post` and we want to access the `created_at` field in the request user's timezone.\r\n\r\n```python\r\nfrom django.db import models\r\n\r\nfrom django_utz.decorators import model\r\n\r\n@model\r\nclass Post(models.Model):\r\n '''Post model'''\r\n title = models.CharField(max_length=255)\r\n content = models.TextField()\r\n author = models.ForeignKey(CustomUser, on_delete=models.CASCADE)\r\n created_at = models.DateTimeField(auto_now_add=True)\r\n updated_at = models.DateTimeField(auto_now=True)\r\n ...\r\n\r\n class UTZMeta:\r\n datetime_fields = \"__all__\"\r\n```\r\n\r\nThe decorator adds a new attribute to the `Post` model called `created_at_utz`. Let's create a post instance and see how this works:\r\n\r\n```python\r\nfrom django.contrib.auth import get_user_model\r\n\r\nUser = get_user_model()\r\n\r\ntolu = User.objects.get(username=\"Tolu\")\r\n\r\nnew_post = Post.objects.create(\r\n title=\"New Post\",\r\n content=\"Lorem Ipsum\",\r\n author=tolu\r\n)\r\n\r\n# If the post was created at 12:00:00 UTC, it will be 13:00:00 in the user's timezone.\r\n# Remember, Tolu's timezone is \"Africa/Lagos\"\r\nprint(new_post.created_at_utz) # 1996-12-19 13:00:00.000200+01:00\r\n```\r\n\r\nThe `model` decorator has a few configurations one of which was used in the model definition above. The configurations are:\r\n\r\n- `datetime_fields`: A list or tuple of the model's datetime fields for which user timezone aware fields should be added. If set to `\"__all__\"`, all datetime fields in the model will have user timezone aware fields added.\r\n\r\n- `use_related_user_timezone`: An optional boolean value that determines if the user timezone aware fields should be based on the timezone of a directly related user, not the request user. This defaults to `False`.\r\n\r\nThe related user in the case of the `Post` model is the `post.author`. If a related user is not found directly in the model, django_utz tries to search for a user in the related models of the model. A related model is usually a model that is linked by a ForeignKey or OneToOneField to the current model.\r\n\r\nTo define explicitly the user whose timezone will be used, you can set this comfiguration to `True` and then defined the path to user on the `related_user` configuration.\r\n\r\n- `related_user`: This is also an optional configuration that specifies the path to the user whose timezone will be used. This is only used when `use_related_user_timezone` is set to `True`. The path is a string that represents the path to the user from the model. The path is in the format `related_model.related_model....user_field`. \r\n\r\nLooks complicated? Let's look at two examples:\r\n\r\n**Example 1:**\r\n\r\nAssume we want all datetime fields in the `Post` model to always be returned in the post author's timezone. We can do this:\r\n\r\n```python\r\nfrom django.db import models\r\n\r\nfrom django_utz.decorators import model\r\n\r\n@model\r\nclass Post(models.Model):\r\n '''Post model'''\r\n title = models.CharField(max_length=255)\r\n content = models.TextField()\r\n author = models.ForeignKey(CustomUser, on_delete=models.CASCADE)\r\n created_at = models.DateTimeField(auto_now_add=True)\r\n updated_at = models.DateTimeField(auto_now=True)\r\n ...\r\n\r\n class UTZMeta:\r\n datetime_fields = \"__all__\"\r\n use_related_user_timezone = True\r\n related_user = \"author\"\r\n```\r\n\r\nSo no matter the user that makes the request, the datetime fields in the `Post` model will always be returned in the post author's timezone.\r\n\r\nYou could also decide to not specify the `related_user` configuration. django_utz will use the first user it finds in the related models of the model. Which is the `author` in this case.\r\n\r\n**Example 2:**\r\n\r\nLet's add a new model called `Comment` that is related to the `Post` model. However, we want all datetime fields in the `Comment` model to always be returned in the post author's timezone. We can do this:\r\n\r\n```python\r\nfrom django.db import models\r\n\r\nfrom django_utz.decorators import model\r\n\r\n@model\r\nclass Comment(models.Model):\r\n '''Comment model'''\r\n post = models.ForeignKey(Post, on_delete=models.CASCADE)\r\n author = models.ForeignKey(CustomUser, on_delete=models.CASCADE)\r\n content = models.TextField()\r\n created_at = models.DateTimeField(auto_now_add=True)\r\n updated_at = models.DateTimeField(auto_now=True)\r\n ...\r\n\r\n class UTZMeta:\r\n datetime_fields = \"__all__\"\r\n use_related_user_timezone = True\r\n related_user = \"post.author\"\r\n```\r\n\r\nIn this case, the `related_user` configuration is set to `\"post.author\"`. This means that the datetime fields in the `Comment` model will always be returned in the post author's timezone, not the comment author's timezone (to be clear, the comment author is the user that made the comment).\r\n\r\nHence, Assuming 'Tolu' already created a new post called 'new_post' and we created a user called 'Tade' with a timezone of \"Asia/Tokyo\", we can do this:\r\n\r\n```python\r\ntade = User.objects.get(username=\"Tade\")\r\n\r\ncomment = Comment.objects.create(\r\n post=new_post,\r\n author=tade,\r\n content=\"Nice post!\"\r\n)\r\n\r\nprint(comment.created_at_utz) # 1996-12-19 13:00:00.000200+01:00 (Africa/Lagos)\r\nprint(comment.author.utz) # Asia/Tokyo\r\nprint(comment.author.to_local_timezone(comment.created_at)) # 1996-12-19 21:00:00.000200+09:00 (Asia/Tokyo)\r\n```\r\n\r\n- `attribute_suffix`: This is an optional configuration that specifies the suffix to be added to the user timezone aware fields. This defaults to \"utz\".\r\n\r\nYou may want to access created_at in the user's timezone as `created_at_local` instead of `created_at_utz`. You can do this:\r\n\r\n```python\r\n\r\n@model\r\nclass Post(models.Model):\r\n '''Post model'''\r\n ...\r\n\r\n class UTZMeta:\r\n ...\r\n attribute_suffix = \"local\"\r\n```\r\n\r\n### The `modelserializer` decorator\r\n\r\nThis decorator is used to decorate django rest framework model serializers. As said at the beginning, this decorator allows you to always return the serializer's model datetime fields in the request user's local timezone or any specified user's local timezone(based on the configurations in the serializer's model) in API responses.\r\n\r\nHowever, for the decorator to work, the serializer's model must have also been decorated with the `model` decorator.\r\n\r\nLet's say we want to create a serializer for our model `Post`:\r\n\r\n```python\r\nfrom rest_framework import serializers\r\nfrom django_utz.decorators import modelserializer\r\n\r\nfrom my_app.models import Post\r\n\r\n@modelserializer\r\nclass PostSerializer(serializers.ModelSerializer):\r\n '''Post serializer'''\r\n class Meta:\r\n model = Post\r\n fields = \"__all__\"\r\n\r\n class UTZMeta:\r\n auto_add_fields = True\r\n\r\n```\r\n\r\nThe available configurations for the `modelserializer` decorator are:\r\n\r\n- `auto_add_fields`: This is a boolean value that determines if the decorator should automatically add timezone aware serializer fields to the serializer. This defaults to `True`.\r\n\r\n- `datetime_format`: This is an optional string that specifies the format to be used when serializing the datetime fields.\r\n\r\n> If you need complete control over the serializer fields, you can set the `auto_add_fields` config to `False` or decide not to decorate the model serializer and then add the timezone aware serializer fields manually. Read more on timezone aware serializer fields [here](#serializer-fields).\r\n\r\nAlso, you do not need to worry about the serializers Meta configuration not been applied. The `modelserializer` decorator respects the Meta configuration of the serializer so all excluded fields, read_only fields, and extra keyword arguments etc will be respected.\r\n\r\n## Fields\r\n\r\n### Serializer Fields\r\n\r\nIn the case that you need complete control over the auto-added serializer fields, you can add user timezone aware serializer datetime fields manually.\r\n\r\n- `UTZDateTimeField`: A serializer field that represents a timezone aware datetime field in the preferred user's local timezone (as defined in the serializer's model).\r\n\r\n```python\r\nfrom rest_framework import serializers\r\n\r\nfrom django_utz.serializers_fields import UTZDateTimeField\r\n\r\nclass PostSerializer(serializers.ModelSerializer):\r\n '''Post serializer'''\r\n created_at = UTZDateTimeField(read_only=True, format=\"%Y-%m-%d %H:%M:%S %Z (%z)\")\r\n updated_at = UTZDateTimeField(read_only=True, label=\"Last updated at\", format=\"%Y-%m-%d %H:%M:%S %Z (%z)\")\r\n\r\n class Meta:\r\n model = Post\r\n fields = \"__all__\"\r\n```\r\n\r\n## Signals\r\n\r\nThe `django_utz.signals` module contains signals that are sent when an event occurs on a user's timezone. The signals are:\r\n\r\n- `user_timezone_changed`: Sent when a user's timezone is updated.\r\n\r\nIn your receiver, you can access the user object, its previous timezone and current timezone with the `instance`, `previous_timezone`and `current_timezone` keyword arguments respectively.\r\n\r\n```python\r\nfrom django.dispatch import receiver\r\nfrom django_utz.signals import user_timezone_changed\r\n\r\n@receiver(user_timezone_changed)\r\ndef user_timezone_changed_receiver(sender, **kwargs):\r\n old_timezone = kwargs.get(\"previous_timezone\")\r\n new_timezone = kwargs.get(\"current_timezone\")\r\n print(old_timezone, new_timezone)\r\n```\r\n\r\n## Templates\r\n\r\n### Template Tags\r\n\r\nThe `django_utz.templatetags.django_utz` module contains a template tag that allows you to display datetime objects in the preferred user's local timezone. To use in a template, load the module in your template:\r\n\r\n```html\r\n{% load django_utz %}\r\n```\r\n\r\n- `usertimezone`: This is a block tag that renders template content with datetime object(s) contained within the block in the request user's timezone but the preferred user can be passed as an argument or keyword argument. Assuming that we want to write a template for our post list view, we can do this:\r\n\r\nHere the datetime objects, `post.created_at` is rendered in the request user's timezone:\r\n\r\n```html\r\n{% load django_utz %}\r\n{% usertimezone %}\r\n {% for post in posts %}\r\n <h3>{{ post.title }}</h3>\r\n <p>{{ post.created_at }}</p>\r\n <p>{{ post.author }}</p>\r\n {% endfor %}\r\n{% endusertimezone %}\r\n```\r\n\r\nSay we want to render the datetime object, `post.created_at` in the timezone of the author of the first post, we can do this:\r\n\r\nFirst approach:\r\n\r\n```html\r\n{% load django_utz %}\r\n{% usertimezone posts[0].author %}\r\n {% for post in posts %}\r\n <h3>{{ post.title }}</h3>\r\n <p>{{ post.created_at }}</p>\r\n <p>{{ post.author }}</p>\r\n {% endfor %}\r\n{% endusertimezone %}\r\n```\r\n\r\nAlternatively;\r\n\r\n```html\r\n{% load django_utz %}\r\n{% usertimezone user=posts[0].author %}\r\n {% for post in posts %}\r\n <h3>{{ post.title }}</h3>\r\n <p>{{ post.created_at }}</p>\r\n <p>{{ post.author }}</p>\r\n {% endfor %}\r\n{% endusertimezone %}\r\n```\r\n\r\n### Template Filters\r\n\r\ndjango_utz also provides a template filter that allows you to display datetime objects in the preferred user's local timezone.\r\n\r\n- `usertimezone`: This filter returns a datetime object in the request user's timezone but the preferred user can be passed as an argument.\r\n\r\nSay we want to write a template for our post detail view, we can do this:\r\n\r\n```html\r\n{% load django_utz %}\r\n\r\n<h3>{{ post.title }}</h3>\r\n<p>{{ post.content }}</p>\r\n<p>{{ post.created_at|usertimezone }}</p>\r\n<p>{{ post.author }}</p>\r\n```\r\n\r\nThis works the same way as the `usertimezone` template tag.\r\nWe can also pass the preferred user as an argument:\r\n\r\n```html\r\n{% load utz %}\r\n\r\n<h3>{{ post.title }}</h3>\r\n<p>{{ post.content }}</p>\r\n<p>{{ post.created_at|usertimezone:post.author }}</p>\r\n<p>{{ post.author }}</p>\r\n```\r\n\r\n## The `utzdatetime` object\r\n\r\nThis is a custom datetime that can be independent of settings.USE_TZ. It inherits from `datetime.datetime`. The reason this exists is because when USE_TZ is set to True, sometimes, datetime objects are converted back to the server's timezone. This can be a problem when you want to view datetime objects in a timezone other than the server's timezone.\r\n\r\nA peculiar case is in templates. If you try to access say, `post.created_at_utz` in a template, you'd get the datetime object in the server's timezone. This is because the datetime object is converted back to the server's timezone when USE_TZ is set to True. Hence, the reason why a `utzdatetime` is used.\r\n\r\nThis object is timezone aware and can be used to display datetime objects in any timezone.\r\n\r\n> This concept was gotten from `django.templatetags.tz`'s `datetimeobject`.\r\n\r\nThe `utzdatetime` object has the following methods:\r\n\r\n- `from_datetime(cls, _datetime: datetime.datetime)`: This class method allows the construction of a `utzdatetime` object from a datetime object.\r\n\r\n```python\r\nimport datetime\r\nfrom django_utz.datetime import utzdatetime\r\n\r\nnormal_datetime = datetime.datetime.now()\r\nutz_datetime = utzdatetime.from_datetime(normal_datetime)\r\n```\r\n\r\n- `regard_usetz()`: This method makes the `utzdatetime` object respect settings.USE_TZ when being converted to a timezone. It may be converted back to server's timezone if USE_TZ is set to True.\r\n\r\n```python\r\nutz_datetime.regard_usetz()\r\n# Now the utzdatetime object is dependent on settings.USE_TZ\r\n```\r\n\r\n- `disregard_usetz()`: This method makes the `utzdatetime` object disregard settings.USE_TZ when being converted to a timezone. It will not be converted back to server's timezone if USE_TZ is set to True.\r\n\r\n```python\r\nutz_datetime.disregard_usetz()\r\n# Now the utzdatetime object is independent of settings.USE_TZ\r\n```\r\n\r\n**Contributions and feedbacks are welcome. For feedbacks, please open an issue. To contribute, please fork the repo and submit a pull request. Thanks!**\r\n",
"bugtrack_url": null,
"license": "",
"summary": "Get datetime values in model instances and model serializers in user's time zone without the need to manually perform timezone conversions for each user.",
"version": "0.1.9",
"project_urls": {
"Bug Tracker": "https://github.com/ti-oluwa/django_utz/issues",
"Homepage": "https://github.com/ti-oluwa/django_utz",
"Repository": "https://github.com/ti-oluwa/django_utz"
},
"split_keywords": [
"user timezone",
"auto timezone conversion",
"django timezone"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "43a7e8a165cd3d131b8a7b4f2fe73cef808e41715c0cd3c257cbad29f4aaac39",
"md5": "35bf684cd9826cd00f43d6f3ac77b9e2",
"sha256": "72def8183582c280f4a5a60c8f889fc432afd67a111b21024b54128157924c27"
},
"downloads": -1,
"filename": "django_utz-0.1.9-py3-none-any.whl",
"has_sig": false,
"md5_digest": "35bf684cd9826cd00f43d6f3ac77b9e2",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.7",
"size": 26371,
"upload_time": "2024-02-10T18:24:13",
"upload_time_iso_8601": "2024-02-10T18:24:13.749461Z",
"url": "https://files.pythonhosted.org/packages/43/a7/e8a165cd3d131b8a7b4f2fe73cef808e41715c0cd3c257cbad29f4aaac39/django_utz-0.1.9-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "1407ae0a6cac5029899bd93bb416765202de5e0c0fa1ab153377985ec80ea1d6",
"md5": "b5b7e86632bf41b2c627f18c1f2491e7",
"sha256": "0dfe01379f0d9c7403e6386ca024fcab468e6bcdab24974aad3c39d85cdb2d4c"
},
"downloads": -1,
"filename": "django_utz-0.1.9.tar.gz",
"has_sig": false,
"md5_digest": "b5b7e86632bf41b2c627f18c1f2491e7",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.7",
"size": 26156,
"upload_time": "2024-02-10T18:24:27",
"upload_time_iso_8601": "2024-02-10T18:24:27.000362Z",
"url": "https://files.pythonhosted.org/packages/14/07/ae0a6cac5029899bd93bb416765202de5e0c0fa1ab153377985ec80ea1d6/django_utz-0.1.9.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-02-10 18:24:27",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "ti-oluwa",
"github_project": "django_utz",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"requirements": [
{
"name": "django",
"specs": []
},
{
"name": "pytz",
"specs": []
},
{
"name": "djangorestframework",
"specs": []
}
],
"lcname": "django-utz"
}
JSON
