{"action":"created","comment":{"url":"https://api.github.com/repos/django/django/pulls/comments/59273731","id":59273731,"diff_hunk":"@@ -293,3 +293,518 @@ Usage example::\n .. versionchanged:: 1.9\n \n     The ability to register the function as a transform was added.\n+\n+Date Functions\n+==============\n+\n+.. module:: django.db.models.functions.date\n+\n+.. versionadded:: 1.10\n+\n+We'll be using the following model in examples of each function::\n+\n+    class Experiment(models.Model):\n+        start_time = models.DateTimeField()\n+        end_time = models.DateTimeField(null=True, blank=True)\n+\n+``Extract``\n+-----------\n+\n+.. class:: Extract(date_expression, lookup_name=None, **extra)\n+\n+Extracts a component of a date as a number.\n+\n+Takes a single ``date_expression`` representing a ``DateField`` or\n+``DateTimeField`` and a ``lookup_name``, and returns the part of the date\n+referenced by ``lookup_name`` as an ``IntegerField``. Django will generally use\n+the databases Extract function, so ``lookup_name``\\s that aren't explicitly\n+referenced below can still be used provided the database supports that value.\n+\n+Given the datetime `2015-06-15 14:30:50.321` the ``lookup_name``\\s supported by\n+Django will return:\n+\n+* \"year\": 2015\n+* \"month\": 6\n+* \"day\": 15\n+* \"week_day\": From 1 (Sunday) to 7 (Saturday)\n+* \"hour\": 14\n+* \"minute\": 30\n+* \"second\": 50\n+\n+.. admonition:: week_day considerations\n+\n+    The ``week_day`` ``lookup_type`` is calculated differently from most\n+    databases and from Python standard functions. This function will return\n+    ``1`` for a Sunday, ``2`` for a Monday, through to ``7`` for a Saturday.\n+\n+    To reach the same result in Python the following calculation should be\n+    used::\n+\n+        >>> from datetime import datetime\n+        >>> dt = datetime(2015, 6, 15, 14, 30, 50, 321)\n+        >>> (dt.isoweekday() % 7) + 1\n+        2\n+\n+The ``lookup_name``\\s above all have corresponding ``Extract`` subclasses that\n+should be preferred in the majority of cases.\n+\n+Usage example::\n+\n+    >>> from datetime import datetime\n+    >>> from django.db.models.functions import Extract\n+    >>> start = datetime(2015, 6, 15)\n+    >>> end = datetime(2015, 7, 2)\n+    >>> Experiment.objects.create(start_time=start, end_time=end)","path":"docs/ref/models/database-functions.txt","position":65,"original_position":65,"commit_id":"613d6e7bf826a9adb890343e9a749dff0f5a4d62","original_commit_id":"613d6e7bf826a9adb890343e9a749dff0f5a4d62","user":{"login":"aaugustin","id":788910,"avatar_url":"https://avatars.githubusercontent.com/u/788910?v=3","gravatar_id":"","url":"https://api.github.com/users/aaugustin","html_url":"https://github.com/aaugustin","followers_url":"https://api.github.com/users/aaugustin/followers","following_url":"https://api.github.com/users/aaugustin/following{/other_user}","gists_url":"https://api.github.com/users/aaugustin/gists{/gist_id}","starred_url":"https://api.github.com/users/aaugustin/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/aaugustin/subscriptions","organizations_url":"https://api.github.com/users/aaugustin/orgs","repos_url":"https://api.github.com/users/aaugustin/repos","events_url":"https://api.github.com/users/aaugustin/events{/privacy}","received_events_url":"https://api.github.com/users/aaugustin/received_events","type":"User","site_admin":false},"body":"Only when `USE_TZ` = True -- but Django encourages that by putting it in the default project template.","created_at":"2016-04-11T20:19:22Z","updated_at":"2016-04-11T20:19:22Z","html_url":"https://github.com/django/django/pull/6243#discussion_r59273731","pull_request_url":"https://api.github.com/repos/django/django/pulls/6243","_links":{"self":{"href":"https://api.github.com/repos/django/django/pulls/comments/59273731"},"html":{"href":"https://github.com/django/django/pull/6243#discussion_r59273731"},"pull_request":{"href":"https://api.github.com/repos/django/django/pulls/6243"}}},"pull_request":{"url":"https://api.github.com/repos/django/django/pulls/6243","id":61810502,"html_url":"https://github.com/django/django/pull/6243","diff_url":"https://github.com/django/django/pull/6243.diff","patch_url":"https://github.com/django/django/pull/6243.patch","issue_url":"https://api.github.com/repos/django/django/issues/6243","number":6243,"state":"open","locked":false,"title":"Fixed #25774 -- Refactor datetime expressions into public API","user":{"login":"jarshwah","id":541083,"avatar_url":"https://avatars.githubusercontent.com/u/541083?v=3","gravatar_id":"","url":"https://api.github.com/users/jarshwah","html_url":"https://github.com/jarshwah","followers_url":"https://api.github.com/users/jarshwah/followers","following_url":"https://api.github.com/users/jarshwah/following{/other_user}","gists_url":"https://api.github.com/users/jarshwah/gists{/gist_id}","starred_url":"https://api.github.com/users/jarshwah/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/jarshwah/subscriptions","organizations_url":"https://api.github.com/users/jarshwah/orgs","repos_url":"https://api.github.com/users/jarshwah/repos","events_url":"https://api.github.com/users/jarshwah/events{/privacy}","received_events_url":"https://api.github.com/users/jarshwah/received_events","type":"User","site_admin":false},"body":"A bunch of datetime transforms/expression are moved and renamed into their own module underneath `django.db.models.functions.datetime`. I'm open to relocating them elsewhere, but I thought it'd be nice to group them within their own file.\r\n\r\nI do plan to implement Trunc expressions too. There's already a high level Date and DateTime type within `expressions.py` which is only used for `.datetimes()` and `.dates()` queryset methods. I might retire those in favour of new public expressions if it's easy enough to do.\r\n\r\nTodo:\r\n- [x] Move and rename existing date/time transforms into public module with public names\r\n- [x] Docs\r\n- [x] Tests\r\n- [x] Implement TruncX in style of ExtractX (with docs/tests) \r\n- [x] Release notes\r\n\r\nThe docs for this change are going to be fairly big, because we've never exposed these types before. Unsure if they should get their own page or if they should just be colocated with existing function docs here: https://docs.djangoproject.com/en/1.9/ref/models/database-functions/","created_at":"2016-03-05T12:13:30Z","updated_at":"2016-04-11T20:19:22Z","closed_at":null,"merged_at":null,"merge_commit_sha":"ca1ba75945813aef067ab58bf98da8688879cb1a","assignee":null,"milestone":null,"commits_url":"https://api.github.com/repos/django/django/pulls/6243/commits","review_comments_url":"https://api.github.com/repos/django/django/pulls/6243/comments","review_comment_url":"https://api.github.com/repos/django/django/pulls/comments{/number}","comments_url":"https://api.github.com/repos/django/django/issues/6243/comments","statuses_url":"https://api.github.com/repos/django/django/statuses/613d6e7bf826a9adb890343e9a749dff0f5a4d62","head":{"label":"jarshwah:refactor-datetime-lookups","ref":"refactor-datetime-lookups","sha":"613d6e7bf826a9adb890343e9a749dff0f5a4d62","user":{"login":"jarshwah","id":541083,"avatar_url":"https://avatars.githubusercontent.com/u/541083?v=3","gravatar_id":"","url":"https://api.github.com/users/jarshwah","html_url":"https://github.com/jarshwah","followers_url":"https://api.github.com/users/jarshwah/followers","following_url":"https://api.github.com/users/jarshwah/following{/other_user}","gists_url":"https://api.github.com/users/jarshwah/gists{/gist_id}","starred_url":"https://api.github.com/users/jarshwah/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/jarshwah/subscriptions","organizations_url":"https://api.github.com/users/jarshwah/orgs","repos_url":"https://api.github.com/users/jarshwah/repos","events_url":"https://api.github.com/users/jarshwah/events{/privacy}","received_events_url":"https://api.github.com/users/jarshwah/received_events","type":"User","site_admin":false},"repo":{"id":4635741,"name":"django","full_name":"jarshwah/django","owner":{"login":"jarshwah","id":541083,"avatar_url":"https://avatars.githubusercontent.com/u/541083?v=3","gravatar_id":"","url":"https://api.github.com/users/jarshwah","html_url":"https://github.com/jarshwah","followers_url":"https://api.github.com/users/jarshwah/followers","following_url":"https://api.github.com/users/jarshwah/following{/other_user}","gists_url":"https://api.github.com/users/jarshwah/gists{/gist_id}","starred_url":"https://api.github.com/users/jarshwah/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/jarshwah/subscriptions","organizations_url":"https://api.github.com/users/jarshwah/orgs","repos_url":"https://api.github.com/users/jarshwah/repos","events_url":"https://api.github.com/users/jarshwah/events{/privacy}","received_events_url":"https://api.github.com/users/jarshwah/received_events","type":"User","site_admin":false},"private":false,"html_url":"https://github.com/jarshwah/django","description":"The Web framework for perfectionists with deadlines. Now on GitHub.","fork":true,"url":"https://api.github.com/repos/jarshwah/django","forks_url":"https://api.github.com/repos/jarshwah/django/forks","keys_url":"https://api.github.com/repos/jarshwah/django/keys{/key_id}","collaborators_url":"https://api.github.com/repos/jarshwah/django/collaborators{/collaborator}","teams_url":"https://api.github.com/repos/jarshwah/django/teams","hooks_url":"https://api.github.com/repos/jarshwah/django/hooks","issue_events_url":"https://api.github.com/repos/jarshwah/django/issues/events{/number}","events_url":"https://api.github.com/repos/jarshwah/django/events","assignees_url":"https://api.github.com/repos/jarshwah/django/assignees{/user}","branches_url":"https://api.github.com/repos/jarshwah/django/branches{/branch}","tags_url":"https://api.github.com/repos/jarshwah/django/tags","blobs_url":"https://api.github.com/repos/jarshwah/django/git/blobs{/sha}","git_tags_url":"https://api.github.com/repos/jarshwah/django/git/tags{/sha}","git_refs_url":"https://api.github.com/repos/jarshwah/django/git/refs{/sha}","trees_url":"https://api.github.com/repos/jarshwah/django/git/trees{/sha}","statuses_url":"https://api.github.com/repos/jarshwah/django/statuses/{sha}","languages_url":"https://api.github.com/repos/jarshwah/django/languages","stargazers_url":"https://api.github.com/repos/jarshwah/django/stargazers","contributors_url":"https://api.github.com/repos/jarshwah/django/contributors","subscribers_url":"https://api.github.com/repos/jarshwah/django/subscribers","subscription_url":"https://api.github.com/repos/jarshwah/django/subscription","commits_url":"https://api.github.com/repos/jarshwah/django/commits{/sha}","git_commits_url":"https://api.github.com/repos/jarshwah/django/git/commits{/sha}","comments_url":"https://api.github.com/repos/jarshwah/django/comments{/number}","issue_comment_url":"https://api.github.com/repos/jarshwah/django/issues/comments{/number}","contents_url":"https://api.github.com/repos/jarshwah/django/contents/{+path}","compare_url":"https://api.github.com/repos/jarshwah/django/compare/{base}...{head}","merges_url":"https://api.github.com/repos/jarshwah/django/merges","archive_url":"https://api.github.com/repos/jarshwah/django/{archive_format}{/ref}","downloads_url":"https://api.github.com/repos/jarshwah/django/downloads","issues_url":"https://api.github.com/repos/jarshwah/django/issues{/number}","pulls_url":"https://api.github.com/repos/jarshwah/django/pulls{/number}","milestones_url":"https://api.github.com/repos/jarshwah/django/milestones{/number}","notifications_url":"https://api.github.com/repos/jarshwah/django/notifications{?since,all,participating}","labels_url":"https://api.github.com/repos/jarshwah/django/labels{/name}","releases_url":"https://api.github.com/repos/jarshwah/django/releases{/id}","deployments_url":"https://api.github.com/repos/jarshwah/django/deployments","created_at":"2012-06-12T09:53:04Z","updated_at":"2015-01-28T00:00:22Z","pushed_at":"2016-04-11T15:46:36Z","git_url":"git://github.com/jarshwah/django.git","ssh_url":"git@github.com:jarshwah/django.git","clone_url":"https://github.com/jarshwah/django.git","svn_url":"https://github.com/jarshwah/django","homepage":"http://www.djangoproject.com/","size":132922,"stargazers_count":1,"watchers_count":1,"language":"Python","has_issues":false,"has_downloads":true,"has_wiki":false,"has_pages":false,"forks_count":0,"mirror_url":null,"open_issues_count":1,"forks":0,"open_issues":1,"watchers":1,"default_branch":"master"}},"base":{"label":"django:master","ref":"master","sha":"db19619545dd99a1d2502c72974d79eca33acff7","user":{"login":"django","id":27804,"avatar_url":"https://avatars.githubusercontent.com/u/27804?v=3","gravatar_id":"","url":"https://api.github.com/users/django","html_url":"https://github.com/django","followers_url":"https://api.github.com/users/django/followers","following_url":"https://api.github.com/users/django/following{/other_user}","gists_url":"https://api.github.com/users/django/gists{/gist_id}","starred_url":"https://api.github.com/users/django/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/django/subscriptions","organizations_url":"https://api.github.com/users/django/orgs","repos_url":"https://api.github.com/users/django/repos","events_url":"https://api.github.com/users/django/events{/privacy}","received_events_url":"https://api.github.com/users/django/received_events","type":"Organization","site_admin":false},"repo":{"id":4164482,"name":"django","full_name":"django/django","owner":{"login":"django","id":27804,"avatar_url":"https://avatars.githubusercontent.com/u/27804?v=3","gravatar_id":"","url":"https://api.github.com/users/django","html_url":"https://github.com/django","followers_url":"https://api.github.com/users/django/followers","following_url":"https://api.github.com/users/django/following{/other_user}","gists_url":"https://api.github.com/users/django/gists{/gist_id}","starred_url":"https://api.github.com/users/django/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/django/subscriptions","organizations_url":"https://api.github.com/users/django/orgs","repos_url":"https://api.github.com/users/django/repos","events_url":"https://api.github.com/users/django/events{/privacy}","received_events_url":"https://api.github.com/users/django/received_events","type":"Organization","site_admin":false},"private":false,"html_url":"https://github.com/django/django","description":"The Web framework for perfectionists with deadlines.","fork":false,"url":"https://api.github.com/repos/django/django","forks_url":"https://api.github.com/repos/django/django/forks","keys_url":"https://api.github.com/repos/django/django/keys{/key_id}","collaborators_url":"https://api.github.com/repos/django/django/collaborators{/collaborator}","teams_url":"https://api.github.com/repos/django/django/teams","hooks_url":"https://api.github.com/repos/django/django/hooks","issue_events_url":"https://api.github.com/repos/django/django/issues/events{/number}","events_url":"https://api.github.com/repos/django/django/events","assignees_url":"https://api.github.com/repos/django/django/assignees{/user}","branches_url":"https://api.github.com/repos/django/django/branches{/branch}","tags_url":"https://api.github.com/repos/django/django/tags","blobs_url":"https://api.github.com/repos/django/django/git/blobs{/sha}","git_tags_url":"https://api.github.com/repos/django/django/git/tags{/sha}","git_refs_url":"https://api.github.com/repos/django/django/git/refs{/sha}","trees_url":"https://api.github.com/repos/django/django/git/trees{/sha}","statuses_url":"https://api.github.com/repos/django/django/statuses/{sha}","languages_url":"https://api.github.com/repos/django/django/languages","stargazers_url":"https://api.github.com/repos/django/django/stargazers","contributors_url":"https://api.github.com/repos/django/django/contributors","subscribers_url":"https://api.github.com/repos/django/django/subscribers","subscription_url":"https://api.github.com/repos/django/django/subscription","commits_url":"https://api.github.com/repos/django/django/commits{/sha}","git_commits_url":"https://api.github.com/repos/django/django/git/commits{/sha}","comments_url":"https://api.github.com/repos/django/django/comments{/number}","issue_comment_url":"https://api.github.com/repos/django/django/issues/comments{/number}","contents_url":"https://api.github.com/repos/django/django/contents/{+path}","compare_url":"https://api.github.com/repos/django/django/compare/{base}...{head}","merges_url":"https://api.github.com/repos/django/django/merges","archive_url":"https://api.github.com/repos/django/django/{archive_format}{/ref}","downloads_url":"https://api.github.com/repos/django/django/downloads","issues_url":"https://api.github.com/repos/django/django/issues{/number}","pulls_url":"https://api.github.com/repos/django/django/pulls{/number}","milestones_url":"https://api.github.com/repos/django/django/milestones{/number}","notifications_url":"https://api.github.com/repos/django/django/notifications{?since,all,participating}","labels_url":"https://api.github.com/repos/django/django/labels{/name}","releases_url":"https://api.github.com/repos/django/django/releases{/id}","deployments_url":"https://api.github.com/repos/django/django/deployments","created_at":"2012-04-28T02:47:18Z","updated_at":"2016-04-11T20:07:00Z","pushed_at":"2016-04-11T16:50:31Z","git_url":"git://github.com/django/django.git","ssh_url":"git@github.com:django/django.git","clone_url":"https://github.com/django/django.git","svn_url":"https://github.com/django/django","homepage":"https://www.djangoproject.com/","size":186317,"stargazers_count":18907,"watchers_count":18907,"language":"Python","has_issues":false,"has_downloads":true,"has_wiki":false,"has_pages":false,"forks_count":7657,"mirror_url":null,"open_issues_count":84,"forks":7657,"open_issues":84,"watchers":18907,"default_branch":"master"}},"_links":{"self":{"href":"https://api.github.com/repos/django/django/pulls/6243"},"html":{"href":"https://github.com/django/django/pull/6243"},"issue":{"href":"https://api.github.com/repos/django/django/issues/6243"},"comments":{"href":"https://api.github.com/repos/django/django/issues/6243/comments"},"review_comments":{"href":"https://api.github.com/repos/django/django/pulls/6243/comments"},"review_comment":{"href":"https://api.github.com/repos/django/django/pulls/comments{/number}"},"commits":{"href":"https://api.github.com/repos/django/django/pulls/6243/commits"},"statuses":{"href":"https://api.github.com/repos/django/django/statuses/613d6e7bf826a9adb890343e9a749dff0f5a4d62"}}}}