{"id":15706707,"url":"https://github.com/danielgtaylor/paodate","last_synced_at":"2025-08-04T18:10:39.557Z","repository":{"id":674973,"uuid":"318509","full_name":"danielgtaylor/paodate","owner":"danielgtaylor","description":"Simpler Python date handling","archived":false,"fork":false,"pushed_at":"2015-04-14T20:57:10.000Z","size":129,"stargazers_count":5,"open_issues_count":1,"forks_count":2,"subscribers_count":3,"default_branch":"master","last_synced_at":"2025-04-20T14:42:35.766Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"http://programmer-art.org","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/danielgtaylor.png","metadata":{"files":{"readme":"README.rst","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2009-09-26T19:13:51.000Z","updated_at":"2022-06-14T02:36:02.000Z","dependencies_parsed_at":"2022-07-05T09:23:23.249Z","dependency_job_id":null,"html_url":"https://github.com/danielgtaylor/paodate","commit_stats":null,"previous_names":[],"tags_count":1,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/danielgtaylor%2Fpaodate","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/danielgtaylor%2Fpaodate/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/danielgtaylor%2Fpaodate/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/danielgtaylor%2Fpaodate/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/danielgtaylor","download_url":"https://codeload.github.com/danielgtaylor/paodate/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":253767318,"owners_count":21961096,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-10-03T20:26:54.283Z","updated_at":"2025-05-12T15:43:27.496Z","avatar_url":"https://github.com/danielgtaylor.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"Pao Date Tools\n==============\nUtilities for making date and time handling in Python easy. This is mainly\naccomplished with the new Date and Delta objects which abstract most of the\ndifferences between datetime, date, time, timedelta, and relativedelta,\nallowing you to convert freely between all of them and providing useful\nutility methods.\n\nPlease note that examples on this page assume a timezone of UTC+1\n(Europe/Amsterdam), as is set before running the unit tests so that all times\nare in a common timezone, otherwise the tests would all be off by some number\nof hours depending on your local timezone.\n\nSome quick examples:\n\n    \u003e\u003e\u003e from paodate import Date\n    \u003e\u003e\u003e Date(1234567890).datetime\n    datetime.datetime(2009, 2, 14, 0, 31, 30)\n\n    \u003e\u003e\u003e d = Date(datetime(2004, 1, 12))\n    \u003e\u003e\u003e d.day += 10\n    \u003e\u003e\u003e d\n    Date(2004-01-22, 00:00:00)\n\n    \u003e\u003e\u003e d.friendly\n    '22 Jan 2004'\n\n    \u003e\u003e\u003e d.sql\n    \"'2004-01-22 00:00:00'\"\n\n    \u003e\u003e\u003e d.month_tuple\n    (Date(2004-01-01, 00:00:00), Date(2004-01-31, 23:59:59))\n\n    \u003e\u003e\u003e delta = Date(1234567890) - d\n    \u003e\u003e\u003e delta\n    Delta(5 years, 1 month, 4 days, 23 hours, 31 minutes, 30 seconds)\n\n    \u003e\u003e\u003e delta.total_seconds\n    160702290.0\n\nConstructors\n------------\nDate objects can be created from just about anything you might want, including\nPython datetime and date objects, struct_time objects, numbers, lists, tuples,\nand strings (which require an extra format parameter):\n\n    \u003e\u003e\u003e Date()\n    # This will be right now in local time on your system\n\n    \u003e\u003e\u003e Date(1234567890)\n    Date(2009-02-14 00:31:30)\n\n    \u003e\u003e\u003e Date(datetime(2009, 2, 14, 0, 31, 30))\n    Date(2009-02-14 00:31:30)\n\n    \u003e\u003e\u003e Date(date(2009, 2, 14))\n    Date(2009-02-14 00:00:00)\n\n    \u003e\u003e\u003e Date(time.localtime(1234567890))\n    Date(2009-02-14 00:31:30)\n\n    \u003e\u003e\u003e Date((2009, 2, 14, 0, 31, 30))\n    Date(2009-02-14, 00:31:30)\n\n    \u003e\u003e\u003e Date(\"2009.02.14 at 00:31:30\", format=\"%Y.%m.%d at %H:%M:%S\")\n    Date(2009-02-14, 00:31:30)\n\nYou can also construct a Date object in the past (or future) by passing in the\nmodification type and amount:\n\n    \u003e\u003e\u003e d = Date(months_ago=3)\n    # This will be three months ago from today in local time\n\n    \u003e\u003e\u003e d = Date(years_ago=1, months_ago=2, days_ago=-5)\n    # One year and two months ago from five days in the future from today\n\nConversion\n----------\nConverting a Date object to any representation you might need is incredibly simple:\n\n    \u003e\u003e\u003e d = Date(1234567890)\n\n    \u003e\u003e\u003e d.datetime\n    datetime.datetime(2009, 2, 14, 0, 31, 30)\n\n    \u003e\u003e\u003e d.date\n    datetime.date(2009, 2, 14)\n\n    \u003e\u003e\u003e d.time\n    datetime.time(0, 31, 30)\n\n    \u003e\u003e\u003e d.tuple\n    time.struct_time(tm_year=2009, tm_mon=2, tm_mday=14, tm_hour=0, tm_min=31,\n                     tm_sec=30, tm_wday=5, tm_yday=45, tm_isdst=-1)\n\n    \u003e\u003e\u003e d.timestamp\n    1234567890\n\nIt is also possible to convert an existing Date object to UTC (this essentially\nremoves time zone information after adjusting by the local offset):\n\n    \u003e\u003e\u003e d.utc\n    Date(2009-02-13, 23:31:30)\n\nComponent Access\n----------------\nAll date and time components of the Date object may be read and written to.\nWhen writing to the components it is good practice to never use absolute values\nand instead use the += and -= operators, as setting negative component values\ncan have unintended effects.\n\n    \u003e\u003e\u003e d = Date(1234567890)\n    \u003e\u003e\u003e d\n    Date(2009-02-14, 00:31:30)\n\n    \u003e\u003e\u003e d.day += 5\n    \u003e\u003e\u003e d\n    Date(2009-02-19, 00:31:30)\n\n    \u003e\u003e\u003e print d.year, d.month, d.day, d.hour, d.minute, d.second, d.microsecond\n    2009, 2, 19, 0, 31, 30, 0\n\n    \u003e\u003e\u003e d.year -= 3\n    \u003e\u003e\u003e d\n    Date(2006-02-19, 00:31:30)\n\nIt's also possible to quickly add / subtract all the components except\nmicroseconds at once or to daisy-chain such operations:\n\n    \u003e\u003e\u003e d.add(years=-2, days=13, minutes=5)\n    # Subtract two years, add 13 days and 5 minutes\n\n    \u003e\u003e\u003e d = Date().start_of_month.add(days=-3)\n    # Get the date and time three days before the start of the current month\n\nThe number of days in the current month is also built-in:\n\n    \u003e\u003e\u003e d.days_in_month\n    28\n\nGetting whether this date is in the past or future is easy as well:\n\n    \u003e\u003e\u003e d.is_past_date\n    True\n    \u003e\u003e\u003e d.is_today\n    False\n    \u003e\u003e\u003e d.is_future_date\n    False\n\nAddition and subtraction of Date objects is also somewhat possible. Addition\nis possible between a Date and Delta or datetime.timedelta, and subtraction\nis possible between Date objects and a Date and a Delta or datetime.timedelta:\n\n    \u003e\u003e\u003e d = Date(1234567890)\n    \u003e\u003e\u003e d2 = Date(1234567900)\n    \u003e\u003e\u003e delta = d2 - d\n    \u003e\u003e\u003e delta\n    Delta(10 seconds)\n    \u003e\u003e\u003e d + delta\n    Date(2009-02-14, 00:31:40)\n\nRelevant Adjacent Dates and Ranges\n----------------------------------\nMany times in an application you need to get the current month, or the current\nday for queries such as all posts from today, the amount to charge a customer\nfor this month, etc. The Date object has all these useful ranges built-in, and\nthey all return new Date objects which you can then convert as you see fit.\n\n    \u003e\u003e\u003e d = Date(1234567890)\n    \u003e\u003e\u003e d\n    Date(2009-02-14, 00:31:30)\n\n    \u003e\u003e\u003e d.start_of_day\n    Date(2009-02-14, 00:00:00)\n    \u003e\u003e\u003e d.end_of_day\n    Date(2009-02-14, 23:59:59)\n    \u003e\u003e\u003e d.day_tuple\n    (Date(2009-02-14, 00:00:00), Date(2009-02-14, 23:59:59))\n    \u003e\u003e\u003e [x.timestamp for x in d.day_tuple]\n    [1234501200, 1234587599]\n\n    \u003e\u003e\u003e d.week_tuple\n    (Date(2009-02-09, 00:00:00), Date(2009-02-15, 23:59:59))\n\n    \u003e\u003e\u003e d.start_of_month\n    Date(2009-02-01, 00:00:00)\n    \u003e\u003e\u003e d.month_tuple\n    (Date(2009-02-01, 00:00:00), Date(2009-02-28, 23:59:59))\n\n    \u003e\u003e\u003e d.end_of_year\n    Date(2009-12-31, 23:59:59)\n    \u003e\u003e\u003e d.year_tuple\n    (Date(2009-01-01, 00:00:00), Date(2009-12-31, 23:59:59))\n\nRepresentation\n--------------\nThe following useful representations are built into the Date object:\n\n    \u003e\u003e\u003e d = Date(1234567890)\n    \u003e\u003e\u003e d.friendly\n    '14 Feb 2009'\n\n    \u003e\u003e\u003e d.fancy\n    'February 14th, 2009'\n    \u003e\u003e\u003e d.fancy_no_year\n    'February 14th'\n\n    \u003e\u003e\u003e d.sql\n    '2009-02-14 00:31:30'\n    \u003e\u003e\u003e d.sql_date\n    '2009-02-14'\n    \u003e\u003e\u003e d.sql_time\n    '00:31:30'\n\n    \u003e\u003e\u003e d.strftime(\"%Y-%m-%d\")\n    '2009-02-14'\n\nDifferences Between Dates\n-------------------------\nThe following examples show how to use the new Delta object with Date objects:\n\n    \u003e\u003e\u003e d1 = Date(1234567890)\n    \u003e\u003e\u003e d2 = Date(1234560000)\n    \u003e\u003e\u003e delta = d1 - d2\n    \u003e\u003e\u003e delta\n    Delta(2 hours, 11 minutes, 30 seconds)\n\n    \u003e\u003e\u003e delta.timedelta\n    datetime.timedelta(0, 7890)\n\n    \u003e\u003e\u003e delta.total_seconds\n    7890.0\n\n    \u003e\u003e\u003e round(delta.total_hours)\n    2.0\n\n    \u003e\u003e\u003e delta.friendly\n    '2 hours, 11 minutes, 30 seconds'\n\n    \u003e\u003e\u003e delta.days = 5\n    \u003e\u003e\u003e delta\n    Delta(5 days, 2 hours, 11 minutes, 30 seconds)\n\n    \u003e\u003e\u003e d2 + delta\n    Date(2009-02-18, 22:31:30)\n\n    \u003e\u003e\u003e (d2 + delta) - d1\n    Delta(5 days)\n\nPlease take a look at the well-documented paodate.py file for more\ninformation.\n\nUsage\n-----\nImport the paodate.py file into your project and use the Date and Delta objects.\n\nRequirements\n------------\nThe only requirement for this module is Python. Running this script will\ninvoke all unit tests so you can see that everything works for your\ninstallation.\n\nAuthors \u0026 Contributors\n----------------------\nPatches are very welcome upstream, so feel free to fork and push your changes\nback up! The following people have worked on this project:\n\n    * Daniel G. Taylor \u003cdan@programmer-art.org\u003e\n    * Nguyễn Hồng Quân \u003cng.hong.quan@gmail.com\u003e\n\nLicense\n-------\nThis module is free software, released under the terms of the Python\nSoftware Foundation License version 2, which can be found here:\n\n    http://www.python.org/psf/license/\n\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdanielgtaylor%2Fpaodate","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdanielgtaylor%2Fpaodate","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdanielgtaylor%2Fpaodate/lists"}