{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Transition from datetime to astropy.time"
   ]
  },
  {
   "cell_type": "raw",
   "metadata": {
    "raw_mimetype": "text/restructuredtext"
   },
   "source": [
    ".. post:: Oct 20, 2018\n",
    "   :author: Vishnunarayan K I\n",
    "   :tags: sunpy, time, gsoc\n",
    "   :category: Google Summer of Code\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    " The SunPy project is very happy to announce that the time handling in SunPy will be transitioned from python `datetime` module to `astropy.time` module.\n",
    "The changes for this transition are under review in the pull request  [#2691]( <https://github.com/sunpy/sunpy/pull/2691>).\n",
    "These changes are scheduled for **SunPy 1.0**.\n",
    "\n",
    "This comes with numerous benefits:"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "**Support for non-UTC time scales**\n",
    "\n",
    "UTC as well as non-UTC time scales like TAI, TT, UT1 etc. can be used with `astropy.time.Time`."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "<Time object: scale='tai' format='isot' value=2012-06-18T02:00:05.453>"
      ]
     },
     "execution_count": 1,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "from astropy.time import Time\n",
    "t = Time('2012-06-18T02:00:05.453', scale='tai')\n",
    "t\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "`~astropy.time.Time` also provides easy conversion between different scales."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 2,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "<Time object: scale='utc' format='isot' value=2012-06-18T01:59:31.453>"
      ]
     },
     "execution_count": 2,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "t.utc\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "**Support for high precision times.**\n",
    "\n",
    "`~astropy.time.Time` can provide sub-nanosecond precision for time objects while python `datetime` was restricted to microseconds."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 3,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "<Time object: scale='tai' format='isot' value=2012-06-18T02:00:05.453000000>"
      ]
     },
     "execution_count": 3,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "t.precision = 9\n",
    "t\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "**Support for leap seconds**\n",
    "\n",
    "This was one of the bigger motivation for the transition to `astropy.time.Time`.\n",
    "`datetime` has no support for leap second while `~astropy.time.Time` supports leap seconds.\n",
    "A leap second is a one-second adjustment applied to UTC to keep it close to the mean solar time."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 4,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "(<Time object: scale='utc' format='isot' value=2016-12-31T23:59:60.000>,\n",
       " <Time object: scale='utc' format='isot' value=2016-12-31T23:59:60.000>)"
      ]
     },
     "execution_count": 4,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "import astropy.units as u\n",
    "Time('2016-12-31T23:59:60'),Time('2016-12-31T23:59:59') + 1 * u.s\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "**Support for numerous formats**\n",
    "\n",
    "`~astropy.time.Time` can parse numerous formats including python `datetime`."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 5,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "OrderedDict([('jd', astropy.time.formats.TimeJD),\n",
       "             ('mjd', astropy.time.formats.TimeMJD),\n",
       "             ('decimalyear', astropy.time.formats.TimeDecimalYear),\n",
       "             ('unix', astropy.time.formats.TimeUnix),\n",
       "             ('cxcsec', astropy.time.formats.TimeCxcSec),\n",
       "             ('gps', astropy.time.formats.TimeGPS),\n",
       "             ('plot_date', astropy.time.formats.TimePlotDate),\n",
       "             ('datetime', astropy.time.formats.TimeDatetime),\n",
       "             ('iso', astropy.time.formats.TimeISO),\n",
       "             ('isot', astropy.time.formats.TimeISOT),\n",
       "             ('yday', astropy.time.formats.TimeYearDayTime),\n",
       "             ('datetime64', astropy.time.formats.TimeDatetime64),\n",
       "             ('fits', astropy.time.formats.TimeFITS),\n",
       "             ('byear', astropy.time.formats.TimeBesselianEpoch),\n",
       "             ('jyear', astropy.time.formats.TimeJulianEpoch),\n",
       "             ('byear_str', astropy.time.formats.TimeBesselianEpochString),\n",
       "             ('jyear_str', astropy.time.formats.TimeJulianEpochString)])"
      ]
     },
     "execution_count": 5,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "Time.FORMATS\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 6,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "<Time object: scale='utc' format='datetime' value=2019-03-20 19:19:05.112429>"
      ]
     },
     "execution_count": 6,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "import datetime\n",
    "Time(datetime.datetime.now())\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Changes to SunPy\n",
    "\n",
    "- **All functions which used to return** `datetime` **now return** `~astropy.time.Time`\n",
    "  - All functions which return `datetime.timedelta` now return `astropy.time.TimeDelta`. \n",
    "    For example, the properties of `sunpy.time.TimeRange` which used to return `datetime.datetime` and `datetime.timedelta` now return `astropy.time.Time` and `astropy.time.TimeDelta`.\n",
    "\n",
    "- **Changes to** `sunpy.time.parse_time`\n",
    "  - `~sunpy.time.parse_time` has been reduced to a tiny wrapper over`~astropy.time.Time`. \n",
    "    The API of `~sunpy.time.parse_time` is mostly similar to that of `~astropy.time.Time`. \n",
    "    `~sunpy.time.parse_time` supports parsing a few more formats than `~astropy.time.Time`, which\n",
    "    are `numpy.datetime64`, `pandas.Series`, `pandas.DatetimeIndex`, \"UTime\" and a few other time formats.\n"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The work on the transition from `datetime` to `astropy.time.Time` was\n",
    "done as a part of Vishnunarayan's Google Summer of Code 2018 project.\n",
    "To see more about the project:\n",
    "\n",
    "-   [Vishnunarayan's Medium Blog\n",
    "    Posts](https://medium.com/@appukuttancr)"
   ]
  }
 ],
 "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": "python",
   "version": "3.7.2"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 2
}