From d95ed97e7369ac79a4f57f6a3cf6a1129925e113 Mon Sep 17 00:00:00 2001 From: Martin Zugnoni Date: Fri, 14 Dec 2018 14:48:26 -0300 Subject: [PATCH] Add DEMO files and link in the README --- DEMO.ipynb | 529 +++++++++++++++++++++++++++++++++++++++++++++++++++++ README.rst | 11 ++ demo.yml | 2 + 3 files changed, 542 insertions(+) create mode 100644 DEMO.ipynb create mode 100644 demo.yml diff --git a/DEMO.ipynb b/DEMO.ipynb new file mode 100644 index 0000000..1cfbbee --- /dev/null +++ b/DEMO.ipynb @@ -0,0 +1,529 @@ +{ + "cells": [ + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "# Maya: Datetimes for Humans™" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "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).\n", + "\n", + "Datetimes should be interacted with via an API written for humans.\n", + "\n", + "Maya is mostly built around the headaches and use-cases around parsing datetime data from websites." + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "## Installing Maya" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "Installation is easy, with `pip`:" + ] + }, + { + "cell_type": "code", + "execution_count": 32, + "metadata": {}, + "outputs": [ + { + "name": "stdout", + "output_type": "stream", + "text": [ + "Requirement already satisfied: maya in /Users/mzugnoni/.virtualenvs/jupyterhub/lib/python3.6/site-packages (0.6.0)\n", + "Requirement already satisfied: pendulum>=2.0.2 in /Users/mzugnoni/.virtualenvs/jupyterhub/lib/python3.6/site-packages (from maya) (2.0.4)\n", + "Requirement already satisfied: dateparser>=0.7.0 in /Users/mzugnoni/.virtualenvs/jupyterhub/lib/python3.6/site-packages (from maya) (0.7.0)\n", + "Requirement already satisfied: humanize in /Users/mzugnoni/.virtualenvs/jupyterhub/lib/python3.6/site-packages (from maya) (0.5.1)\n", + "Requirement already satisfied: snaptime in /Users/mzugnoni/.virtualenvs/jupyterhub/lib/python3.6/site-packages (from maya) (0.2.4)\n", + "Requirement already satisfied: tzlocal in /Users/mzugnoni/.virtualenvs/jupyterhub/lib/python3.6/site-packages (from maya) (1.5.1)\n", + "Requirement already satisfied: pytz in /Users/mzugnoni/.virtualenvs/jupyterhub/lib/python3.6/site-packages (from maya) (2018.5)\n", + "Requirement already satisfied: pytzdata>=2018.3 in /Users/mzugnoni/.virtualenvs/jupyterhub/lib/python3.6/site-packages (from pendulum>=2.0.2->maya) (2018.7)\n", + "Requirement already satisfied: python-dateutil<3.0,>=2.6 in /Users/mzugnoni/.virtualenvs/jupyterhub/lib/python3.6/site-packages (from pendulum>=2.0.2->maya) (2.7.3)\n", + "Requirement already satisfied: regex in /Users/mzugnoni/.virtualenvs/jupyterhub/lib/python3.6/site-packages (from dateparser>=0.7.0->maya) (2018.11.22)\n", + "Requirement already satisfied: six>=1.5 in /Users/mzugnoni/.virtualenvs/jupyterhub/lib/python3.6/site-packages (from python-dateutil<3.0,>=2.6->pendulum>=2.0.2->maya) (1.11.0)\n", + "\u001b[33mYou are using pip version 18.0, however version 18.1 is available.\n", + "You should consider upgrading via the 'pip install --upgrade pip' command.\u001b[0m\n" + ] + } + ], + "source": [ + "!pip install maya" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "## Basic Usage of Maya" + ] + }, + { + "cell_type": "code", + "execution_count": 33, + "metadata": {}, + "outputs": [], + "source": [ + "import maya" + ] + }, + { + "cell_type": "code", + "execution_count": 34, + "metadata": {}, + "outputs": [ + { + "data": { + "text/plain": [ + "" + ] + }, + "execution_count": 34, + "metadata": {}, + "output_type": "execute_result" + } + ], + "source": [ + "maya.now()" + ] + }, + { + "cell_type": "code", + "execution_count": 35, + "metadata": {}, + "outputs": [ + { + "data": { + "text/plain": [ + "" + ] + }, + "execution_count": 35, + "metadata": {}, + "output_type": "execute_result" + } + ], + "source": [ + "tomorrow = maya.when('tomorrow')\n", + "tomorrow" + ] + }, + { + "cell_type": "code", + "execution_count": 36, + "metadata": {}, + "outputs": [ + { + "data": { + "text/plain": [ + "'tomorrow'" + ] + }, + "execution_count": 36, + "metadata": {}, + "output_type": "execute_result" + } + ], + "source": [ + "tomorrow.slang_date()" + ] + }, + { + "cell_type": "code", + "execution_count": 37, + "metadata": {}, + "outputs": [ + { + "data": { + "text/plain": [ + "'in 23 hours'" + ] + }, + "execution_count": 37, + "metadata": {}, + "output_type": "execute_result" + } + ], + "source": [ + "tomorrow.slang_time()" + ] + }, + { + "cell_type": "code", + "execution_count": 38, + "metadata": {}, + "outputs": [ + { + "data": { + "text/plain": [ + "'2018-12-15T17:45:14.872356Z'" + ] + }, + "execution_count": 38, + "metadata": {}, + "output_type": "execute_result" + } + ], + "source": [ + "# Also: MayaDT.from_iso8601(...)\n", + "tomorrow.iso8601()" + ] + }, + { + "cell_type": "code", + "execution_count": 39, + "metadata": {}, + "outputs": [ + { + "data": { + "text/plain": [ + "'Sat, 15 Dec 2018 17:45:14 GMT'" + ] + }, + "execution_count": 39, + "metadata": {}, + "output_type": "execute_result" + } + ], + "source": [ + "# Also: MayaDT.from_rfc2822(...)\n", + "tomorrow.rfc2822()" + ] + }, + { + "cell_type": "code", + "execution_count": 40, + "metadata": {}, + "outputs": [ + { + "data": { + "text/plain": [ + "'2018-12-15T17:45:14.8Z'" + ] + }, + "execution_count": 40, + "metadata": {}, + "output_type": "execute_result" + } + ], + "source": [ + "# Also: MayaDT.from_rfc3339(...)\n", + "tomorrow.rfc3339()" + ] + }, + { + "cell_type": "code", + "execution_count": 41, + "metadata": {}, + "outputs": [ + { + "data": { + "text/plain": [ + "datetime.datetime(2018, 12, 15, 17, 45, 14, 872356, tzinfo=)" + ] + }, + "execution_count": 41, + "metadata": {}, + "output_type": "execute_result" + } + ], + "source": [ + "tomorrow.datetime()" + ] + }, + { + "cell_type": "code", + "execution_count": 42, + "metadata": {}, + "outputs": [ + { + "data": { + "text/plain": [ + "datetime.datetime(2016, 12, 16, 13, 23, 45, 423992)" + ] + }, + "execution_count": 42, + "metadata": {}, + "output_type": "execute_result" + } + ], + "source": [ + "# 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)" + ] + }, + { + "cell_type": "code", + "execution_count": 43, + "metadata": {}, + "outputs": [], + "source": [ + "rand_day = maya.when('2011-02-07', timezone='US/Eastern')" + ] + }, + { + "cell_type": "code", + "execution_count": 44, + "metadata": {}, + "outputs": [ + { + "data": { + "text/plain": [ + "" + ] + }, + "execution_count": 44, + "metadata": {}, + "output_type": "execute_result" + } + ], + "source": [ + "# Maya speaks Python.\n", + "from datetime import datetime\n", + "\n", + "maya.MayaDT.from_datetime(datetime.utcnow())" + ] + }, + { + "cell_type": "code", + "execution_count": 45, + "metadata": {}, + "outputs": [ + { + "data": { + "text/plain": [ + "" + ] + }, + "execution_count": 45, + "metadata": {}, + "output_type": "execute_result" + } + ], + "source": [ + "import time\n", + "\n", + "maya.MayaDT.from_struct(time.gmtime())" + ] + }, + { + "cell_type": "code", + "execution_count": 46, + "metadata": {}, + "outputs": [ + { + "data": { + "text/plain": [ + "" + ] + }, + "execution_count": 46, + "metadata": {}, + "output_type": "execute_result" + } + ], + "source": [ + "maya.MayaDT(time.time())" + ] + }, + { + "cell_type": "code", + "execution_count": 47, + "metadata": {}, + "outputs": [ + { + "data": { + "text/plain": [ + "7" + ] + }, + "execution_count": 47, + "metadata": {}, + "output_type": "execute_result" + } + ], + "source": [ + "rand_day.day" + ] + }, + { + "cell_type": "code", + "execution_count": 48, + "metadata": {}, + "outputs": [ + { + "data": { + "text/plain": [ + "17" + ] + }, + "execution_count": 48, + "metadata": {}, + "output_type": "execute_result" + } + ], + "source": [ + "rand_day.add(days=10).day" + ] + }, + { + "cell_type": "code", + "execution_count": 49, + "metadata": {}, + "outputs": [ + { + "data": { + "text/plain": [ + "'UTC'" + ] + }, + "execution_count": 49, + "metadata": {}, + "output_type": "execute_result" + } + ], + "source": [ + "# Always.\n", + "rand_day.timezone" + ] + }, + { + "cell_type": "code", + "execution_count": 50, + "metadata": {}, + "outputs": [ + { + "data": { + "text/plain": [ + "" + ] + }, + "execution_count": 50, + "metadata": {}, + "output_type": "execute_result" + } + ], + "source": [ + "# Range of hours in a day:\n", + "maya.intervals(start=maya.now(), end=maya.now().add(days=1), interval=60*60)" + ] + }, + { + "cell_type": "code", + "execution_count": 51, + "metadata": {}, + "outputs": [ + { + "data": { + "text/plain": [ + "'Mon, 21 Feb 1994 03:00:00 GMT'" + ] + }, + "execution_count": 51, + "metadata": {}, + "output_type": "execute_result" + } + ], + "source": [ + "# snap modifiers\n", + "dt = maya.when('Mon, 21 Feb 1994 21:21:42 GMT')\n", + "dt.snap('@d+3h').rfc2822()" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "## Advanced Usage of Maya" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "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.\n", + "\n", + "For example:" + ] + }, + { + "cell_type": "code", + "execution_count": 52, + "metadata": {}, + "outputs": [], + "source": [ + "from maya import MayaInterval" + ] + }, + { + "cell_type": "code", + "execution_count": 53, + "metadata": {}, + "outputs": [], + "source": [ + "# Create an event that is one hour long, starting now.\n", + "event_start = maya.now()\n", + "event_end = event_start.add(hours=1)" + ] + }, + { + "cell_type": "code", + "execution_count": 54, + "metadata": {}, + "outputs": [ + { + "data": { + "text/plain": [ + " end=>" + ] + }, + "execution_count": 54, + "metadata": {}, + "output_type": "execute_result" + } + ], + "source": [ + "MayaInterval(start=event_start, end=event_end)" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "From here, there are a number of methods available to you, which you can use to compare this event to another event." + ] + } + ], + "metadata": { + "kernelspec": { + "display_name": "Python 3", + "language": "python", + "name": "python3" + }, + "language_info": { + "codemirror_mode": { + "name": "ipython", + "version": 3 + }, + "file_extension": ".py", + "mimetype": "text/x-python", + "name": "python", + "nbconvert_exporter": "python", + "pygments_lexer": "ipython3", + "version": "3.6.5" + } + }, + "nbformat": 4, + "nbformat_minor": 2 +} diff --git a/README.rst b/README.rst index dc8f247..8b6c555 100644 --- a/README.rst +++ b/README.rst @@ -156,6 +156,17 @@ Installation is easy, with `pipenv `_:: ✨🍰✨ + +☤ Demo +------ + +Try ``maya`` interactively using this online demo: + +.. image:: https://user-images.githubusercontent.com/1155573/49400125-16e73500-f722-11e8-9275-e1d7eb3bbf99.png + :target: https://notebooks.rmotr.com/demo/gh/martinzugnoni/maya + :alt: Open Live Demo + + ☤ Like it? ---------- diff --git a/demo.yml b/demo.yml new file mode 100644 index 0000000..5081f88 --- /dev/null +++ b/demo.yml @@ -0,0 +1,2 @@ +requirements: + - maya==0.6.0 \ No newline at end of file