Skip to main content

Datetimes for Humans.

Project description

https://img.shields.io/pypi/v/maya.svg https://travis-ci.org/kennethreitz/maya.svg?branch=master https://img.shields.io/badge/SayThanks.io-☼-1EAEDB.svg

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.

☤ Basic Usage of Maya

Behold, datetimes for humans!

>>> 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'

>>> tomorrow.iso8601()
'2016-12-16T15:11:30.263350Z'

>>> tomorrow.rfc2822()
'Fri, 16 Dec 2016 20:11:30 -0000'

>>> 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>

# Note how this is the 6th, not the 7th.
>>> rand_day.day
6

# Always.
>>> rand_day.timezone
UTC

☤ 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?

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. For example- Arrow supports floors and ceilings and spans of dates, which Maya does not at all.

☤ Installing Maya

Installation is easy, with pip:

$ pip install maya

✨🍰✨

☤ Like it?

Say Thanks!

How to Contribute

  1. Check for open issues or open a fresh issue to start a discussion around a feature idea or a bug.

  2. Fork the repository on GitHub to start making your changes to the master branch (or branch off of it).

  3. Write a test which shows that the bug was fixed or that the feature works as expected.

  4. Send a pull request and bug the maintainer until it gets merged and published. :) Make sure to add yourself to AUTHORS.

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

maya-0.1.7.tar.gz (5.5 kB view details)

Uploaded Source

Built Distribution

maya-0.1.7-py3-none-any.whl (7.9 kB view details)

Uploaded Python 3

File details

Details for the file maya-0.1.7.tar.gz.

File metadata

  • Download URL: maya-0.1.7.tar.gz
  • Upload date:
  • Size: 5.5 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? No

File hashes

Hashes for maya-0.1.7.tar.gz
Algorithm Hash digest
SHA256 28953538d8de94163089a9d9ab72f6cf926cbc7b527a2c1b9f3004bb5368e80a
MD5 08be4246117ac2ae8814e3f1ea511d8c
BLAKE2b-256 1b2c95dfee79f3e2e98c661b86913e0e828ba1b5e823a36aa8523689bf38cd51

See more details on using hashes here.

Provenance

File details

Details for the file maya-0.1.7-py3-none-any.whl.

File metadata

File hashes

Hashes for maya-0.1.7-py3-none-any.whl
Algorithm Hash digest
SHA256 e334dd24e2c0f3b9131ca2dcd04591feff500787c8013888205234d622973bc6
MD5 8b2e18ac70378f888511533a8d58ba50
BLAKE2b-256 a4018b7bcf79c20639d86149bca4c0acf9a02cf97dad3d35ad9a17f491d1bc3b

See more details on using hashes here.

Provenance

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page