Maya: Datetimes for Humans™
===========================
.. image:: https://img.shields.io/pypi/v/maya.svg
:target: https://pypi.python.org/pypi/maya
.. image:: https://travis-ci.org/kennethreitz/maya.svg?branch=master
:target: https://travis-ci.org/kennethreitz/maya
.. image:: https://img.shields.io/badge/SayThanks-!-1EAEDB.svg
:target: https://saythanks.io/to/kennethreitz
Datetimes are very frustrating to work with in Python, especially when dealing
with different locales on different systems. This library exists to make the
simple things **much** easier, while admitting that time is an illusion
(timezones doubly so).
Datetimes should be interacted with via an API written for humans.
Maya is mostly built around the headaches and use-cases around parsing datetime data from websites.
.. image:: https://farm4.staticflickr.com/3702/33288285996_5b69d2b8f7_k_d.jpg
Art by `Sam Flores
<https://www.instagram.com/samagram12/>`_ (Photo by `Kenneth Reitz
<https://www.instagram.com/kennethreitz/>`_).
If you're interested in financially supporting Kenneth Reitz open source, consider `visiting this link <https://cash.me/$KennethReitz>`_. Your support helps tremendously with sustainability of motivation, as Open Source is no longer part of my day job.
☤ Basic Usage of Maya
---------------------
Behold, datetimes for humans!
.. code-block:: pycon
>>> now = maya.now()
<MayaDT epoch=1481850660.9>
>>> tomorrow = maya.when('tomorrow')
<MayaDT epoch=1481919067.23>
>>> tomorrow.slang_date()
'tomorrow'
>>> tomorrow.slang_time()
'23 hours from now'
# Also: MayaDT.from_iso8601(...)
>>> tomorrow.iso8601()
'2017-02-10T22:17:01.445418Z'
# Also: MayaDT.from_rfc2822(...)
>>> tomorrow.rfc2822()
'Fri, 10 Feb 2017 22:17:01 GMT'
# Also: MayaDT.from_rfc3339(...)
>>> tomorrow.rfc3339()
'2017-02-10T22:17:01.44Z'
>>> tomorrow.datetime()
datetime.datetime(2016, 12, 16, 15, 11, 30, 263350, tzinfo=<UTC>)
# Automatically parse datetime strings and generate naive datetimes.
>>> scraped = '2016-12-16 18:23:45.423992+00:00'
>>> maya.parse(scraped).datetime(to_timezone='US/Eastern', naive=True)
datetime.datetime(2016, 12, 16, 13, 23, 45, 423992)
>>> rand_day = maya.when('2011-02-07', timezone='US/Eastern')
<MayaDT epoch=1297036800.0>
# Maya speaks Python.
>>> m = maya.MayaDT.from_datetime(datetime.utcnow())
>>> print(m)
Wed, 20 Sep 2017 17:24:32 GMT
>>> m = maya.MayaDT.from_struct(time.gmtime())
>>> print(m)
Wed, 20 Sep 2017 17:24:32 GMT
>>> m = maya.MayaDT(time.time())
>>> print(m)
Wed, 20 Sep 2017 17:24:32 GMT
>>> rand_day.day
7
>>> rand_day.add(days=10).day
17
# Always.
>>> rand_day.timezone
UTC
# Range of hours in a day:
>>> maya.intervals(start=maya.now(), end=maya.now().add(days=1), interval=60*60)
<generator object intervals at 0x105ba5820>
# snap modifiers
>>> dt = maya.when('Mon, 21 Feb 1994 21:21:42 GMT')
>>> dt.snap('@d+3h').rfc2822()
'Mon, 21 Feb 1994 03:00:00 GMT'
☤ Advanced Usage of Maya
------------------------
In addition to timestamps, Maya also includes a wonderfully powerful ``MayaInterval`` class, which represents a range of time (e.g. an event). With this class, you can perform a multitude of advanced calendar calculations with finesse and ease.
For example:
.. code-block:: pycon
>>> from maya import MayaInterval
# Create an event that is one hour long, starting now.
>>> event_start = maya.now()
>>> event_end = event_start.add(hours=1)
>>> event = MayaInterval(start=event_start, end=event_end)
From here, there are a number of methods available to you, which you can use to compare this event to another event.
☤ Why is this useful?
---------------------
- All timezone algebra will behave identically on all machines, regardless of system locale.
- Complete symmetric import and export of both ISO 8601 and RFC 2822 datetime stamps.
- Fantastic parsing of both dates written for/by humans and machines (``maya.when()`` vs ``maya.parse()``).
- Support for human slang, both import and export (e.g. `an hour ago`).
- Datetimes can very easily be generated, with or without tzinfo attached.
- This library is based around epoch time, but dates before Jan 1 1970 are indeed supported, via negative integers.
- Maya never panics, and always carries a towel.
☤ What about Delorean, Arrow, & Pendulum?
-----------------------------------------
All these projects complement each other, and are friends. Pendulum, for example, helps power Maya's parsing.
Arrow, for example, is a fantastic library, but isn't what I wanted in a datetime library. In many ways, it's better than Maya for certain things. In some ways, in my opinion, it's not.
I simply desire a sane API for datetimes that made sense to me for all the things I'd ever want to do—especially when dealing with timezone algebra. Arrow doesn't do all of the things I need (but it does a lot more!). Maya does do exactly what I need.
I think these projects complement each-other, personally. Maya is great for parsing websites, and dealing with calendar events!
☤ Installing Maya
-----------------
Installation is easy, with `pipenv <http://pipenv.org/>`_::
$ pipenv install maya
✨🍰✨
☤ Like it?
----------
`Say Thanks <https://saythanks.io/to/kennethreitz>`_!
How to Contribute
-----------------
#. Check for open issues or open a fresh issue to start a discussion around a feature idea or a bug.
#. Fork `the repository`_ on GitHub to start making your changes to the **master** branch (or branch off of it).
#. Write a test which shows that the bug was fixed or that the feature works as expected.
#. Send a pull request and bug the maintainer until it gets merged and published. :) Make sure to add yourself to AUTHORS_.
.. _`the repository`: http://github.com/kennethreitz/maya
.. _AUTHORS: https://github.com/kennethreitz/maya/blob/master/AUTHORS.rst
Raw data
{
"_id": null,
"home_page": "https://github.com/kennethreitz/maya",
"name": "maya",
"maintainer": "",
"docs_url": null,
"requires_python": "",
"maintainer_email": "",
"keywords": "",
"author": "Kenneth Reitz",
"author_email": "me@kennethreitz.org",
"download_url": "https://files.pythonhosted.org/packages/4e/90/e0e298b495164475331cc3fda906c640c9098a49fc933172fe5826393185/maya-0.6.1.tar.gz",
"platform": "",
"description": "\nMaya: Datetimes for Humans\u2122\n===========================\n\n.. image:: https://img.shields.io/pypi/v/maya.svg\n :target: https://pypi.python.org/pypi/maya\n\n.. image:: https://travis-ci.org/kennethreitz/maya.svg?branch=master\n :target: https://travis-ci.org/kennethreitz/maya\n\n.. image:: https://img.shields.io/badge/SayThanks-!-1EAEDB.svg\n :target: https://saythanks.io/to/kennethreitz\n\n\nDatetimes are very frustrating to work with in Python, especially when dealing\nwith different locales on different systems. This library exists to make the\nsimple things **much** easier, while admitting that time is an illusion\n(timezones doubly so).\n\nDatetimes should be interacted with via an API written for humans.\n\nMaya is mostly built around the headaches and use-cases around parsing datetime data from websites.\n\n.. image:: https://farm4.staticflickr.com/3702/33288285996_5b69d2b8f7_k_d.jpg\n\nArt by `Sam Flores\n<https://www.instagram.com/samagram12/>`_ (Photo by `Kenneth Reitz\n<https://www.instagram.com/kennethreitz/>`_). \n\nIf you're interested in financially supporting Kenneth Reitz open source, consider `visiting this link <https://cash.me/$KennethReitz>`_. Your support helps tremendously with sustainability of motivation, as Open Source is no longer part of my day job.\n\n\u2624 Basic Usage of Maya\n---------------------\n\nBehold, datetimes for humans!\n\n.. code-block:: pycon\n\n >>> now = maya.now()\n <MayaDT epoch=1481850660.9>\n\n >>> tomorrow = maya.when('tomorrow')\n <MayaDT epoch=1481919067.23>\n\n >>> tomorrow.slang_date()\n 'tomorrow'\n\n >>> tomorrow.slang_time()\n '23 hours from now'\n\n # Also: MayaDT.from_iso8601(...)\n >>> tomorrow.iso8601()\n '2017-02-10T22:17:01.445418Z'\n\n # Also: MayaDT.from_rfc2822(...)\n >>> tomorrow.rfc2822()\n 'Fri, 10 Feb 2017 22:17:01 GMT'\n\n # Also: MayaDT.from_rfc3339(...)\n >>> tomorrow.rfc3339()\n '2017-02-10T22:17:01.44Z'\n\n >>> tomorrow.datetime()\n datetime.datetime(2016, 12, 16, 15, 11, 30, 263350, tzinfo=<UTC>)\n\n # Automatically parse datetime strings and generate naive datetimes.\n >>> scraped = '2016-12-16 18:23:45.423992+00:00'\n >>> maya.parse(scraped).datetime(to_timezone='US/Eastern', naive=True)\n datetime.datetime(2016, 12, 16, 13, 23, 45, 423992)\n\n >>> rand_day = maya.when('2011-02-07', timezone='US/Eastern')\n <MayaDT epoch=1297036800.0>\n\n # Maya speaks Python.\n >>> m = maya.MayaDT.from_datetime(datetime.utcnow())\n >>> print(m)\n Wed, 20 Sep 2017 17:24:32 GMT\n\n >>> m = maya.MayaDT.from_struct(time.gmtime())\n >>> print(m)\n Wed, 20 Sep 2017 17:24:32 GMT\n\n >>> m = maya.MayaDT(time.time())\n >>> print(m)\n Wed, 20 Sep 2017 17:24:32 GMT\n\n >>> rand_day.day\n 7\n\n >>> rand_day.add(days=10).day\n 17\n\n # Always.\n >>> rand_day.timezone\n UTC\n\n # Range of hours in a day:\n >>> maya.intervals(start=maya.now(), end=maya.now().add(days=1), interval=60*60)\n <generator object intervals at 0x105ba5820>\n\n # snap modifiers\n >>> dt = maya.when('Mon, 21 Feb 1994 21:21:42 GMT')\n >>> dt.snap('@d+3h').rfc2822()\n 'Mon, 21 Feb 1994 03:00:00 GMT'\n\n\u2624 Advanced Usage of Maya\n------------------------\n\nIn addition to timestamps, Maya also includes a wonderfully powerful ``MayaInterval`` class, which represents a range of time (e.g. an event). With this class, you can perform a multitude of advanced calendar calculations with finesse and ease.\n\nFor example:\n\n.. code-block:: pycon\n\n >>> from maya import MayaInterval\n\n # Create an event that is one hour long, starting now.\n >>> event_start = maya.now()\n >>> event_end = event_start.add(hours=1)\n\n >>> event = MayaInterval(start=event_start, end=event_end)\n\nFrom here, there are a number of methods available to you, which you can use to compare this event to another event.\n\n\n\n\u2624 Why is this useful?\n---------------------\n\n- All timezone algebra will behave identically on all machines, regardless of system locale.\n- Complete symmetric import and export of both ISO 8601 and RFC 2822 datetime stamps.\n- Fantastic parsing of both dates written for/by humans and machines (``maya.when()`` vs ``maya.parse()``).\n- Support for human slang, both import and export (e.g. `an hour ago`).\n- Datetimes can very easily be generated, with or without tzinfo attached.\n- This library is based around epoch time, but dates before Jan 1 1970 are indeed supported, via negative integers.\n- Maya never panics, and always carries a towel.\n\n\n\u2624 What about Delorean, Arrow, & Pendulum?\n-----------------------------------------\n\nAll these projects complement each other, and are friends. Pendulum, for example, helps power Maya's parsing.\n\nArrow, for example, is a fantastic library, but isn't what I wanted in a datetime library. In many ways, it's better than Maya for certain things. In some ways, in my opinion, it's not.\n\nI simply desire a sane API for datetimes that made sense to me for all the things I'd ever want to do\u2014especially when dealing with timezone algebra. Arrow doesn't do all of the things I need (but it does a lot more!). Maya does do exactly what I need.\n\nI think these projects complement each-other, personally. Maya is great for parsing websites, and dealing with calendar events!\n\n\n\u2624 Installing Maya\n-----------------\n\nInstallation is easy, with `pipenv <http://pipenv.org/>`_::\n\n $ pipenv install maya\n\n\u2728\ud83c\udf70\u2728\n\n\u2624 Like it?\n----------\n\n`Say Thanks <https://saythanks.io/to/kennethreitz>`_!\n\n\nHow to Contribute\n-----------------\n\n#. Check for open issues or open a fresh issue to start a discussion around a feature idea or a bug.\n#. Fork `the repository`_ on GitHub to start making your changes to the **master** branch (or branch off of it).\n#. Write a test which shows that the bug was fixed or that the feature works as expected.\n#. Send a pull request and bug the maintainer until it gets merged and published. :) Make sure to add yourself to AUTHORS_.\n\n.. _`the repository`: http://github.com/kennethreitz/maya\n.. _AUTHORS: https://github.com/kennethreitz/maya/blob/master/AUTHORS.rst\n\n\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Datetimes for Humans.",
"version": "0.6.1",
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"md5": "d19c4050a3df41550643634442c55e08",
"sha256": "fa90d8c6c9a730a7f740dec6e1c7d3da8ca10159e40bb843e4e72772f5e3a9a3"
},
"downloads": -1,
"filename": "maya-0.6.1-py2.py3-none-any.whl",
"has_sig": false,
"md5_digest": "d19c4050a3df41550643634442c55e08",
"packagetype": "bdist_wheel",
"python_version": "py2.py3",
"requires_python": null,
"size": 12772,
"upload_time": "2019-01-06T11:23:20",
"upload_time_iso_8601": "2019-01-06T11:23:20.631101Z",
"url": "https://files.pythonhosted.org/packages/1d/56/789ebf410acc1491bf4078ef57a7a277b42c0b18f43e17007bfb6c1caaf3/maya-0.6.1-py2.py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"md5": "7f91fea8c17317957843699777026856",
"sha256": "7f53e06d5a123613dce7c270cbc647643a6942590dba7a19ec36194d0338c3f4"
},
"downloads": -1,
"filename": "maya-0.6.1.tar.gz",
"has_sig": false,
"md5_digest": "7f91fea8c17317957843699777026856",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 14387,
"upload_time": "2019-01-06T11:23:22",
"upload_time_iso_8601": "2019-01-06T11:23:22.495004Z",
"url": "https://files.pythonhosted.org/packages/4e/90/e0e298b495164475331cc3fda906c640c9098a49fc933172fe5826393185/maya-0.6.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2019-01-06 11:23:22",
"github": true,
"gitlab": false,
"bitbucket": false,
"github_user": "kennethreitz",
"github_project": "maya",
"travis_ci": false,
"coveralls": true,
"github_actions": true,
"tox": true,
"lcname": "maya"
}
JSON
