.. image:: https://github.com/adamjstewart/fiscalyear/actions/workflows/style.yaml/badge.svg
:target: https://github.com/adamjstewart/fiscalyear/actions/workflows/style.yaml
.. image:: https://github.com/adamjstewart/fiscalyear/actions/workflows/tests.yaml/badge.svg
:target: https://github.com/adamjstewart/fiscalyear/actions/workflows/tests.yaml
.. image:: https://codecov.io/gh/adamjstewart/fiscalyear/branch/master/graph/badge.svg
:target: https://codecov.io/gh/adamjstewart/fiscalyear
.. image:: https://readthedocs.org/projects/fiscalyear/badge/?version=latest
:target: https://fiscalyear.readthedocs.io
.. image:: https://badge.fury.io/py/fiscalyear.svg
:target: https://pypi.org/project/fiscalyear/
.. image:: https://anaconda.org/conda-forge/fiscalyear/badges/version.svg
:target: https://anaconda.org/conda-forge/fiscalyear
.. image:: https://img.shields.io/spack/v/py-torchgeo
:target: https://spack.readthedocs.io/en/latest/package_list.html#py-torchgeo
Overview
========
`fiscalyear <https://github.com/adamjstewart/fiscalyear>`_ is a small, lightweight Python module providing helpful utilities for managing the fiscal calendar. It is designed as an extension of the built-in `datetime <https://docs.python.org/3/library/datetime.html>`_ and `calendar <https://docs.python.org/3/library/calendar.html>`_ modules, adding the ability to query the fiscal year, fiscal quarter, fiscal month, and fiscal day of a date or datetime object.
Basic Usage
===========
``fiscalyear`` provides several useful classes.
FiscalYear
----------
The ``FiscalYear`` class provides an object for storing information about the start and end of a particular fiscal year.
.. code-block:: python
>>> from fiscalyear import *
>>> a = FiscalYear(2017)
>>> a.start
FiscalDateTime(2016, 10, 1, 0, 0)
>>> a.end
FiscalDateTime(2017, 9, 30, 23, 59, 59)
>>> a.isleap
False
You can also get the current ``FiscalYear`` with:
.. code-block:: python
>>> FiscalYear.current()
FiscalYear(2018)
FiscalQuarter
-------------
The ``FiscalYear`` class also allows you to query information about a specific fiscal quarter.
.. code-block:: python
>>> a.q3.start
FiscalDateTime(2017, 4, 1, 0, 0)
>>> a.q3.end
FiscalDateTime(2017, 6, 30, 23, 59, 59)
These objects represent the standalone ``FiscalQuarter`` class.
.. code-block:: python
>>> b = FiscalQuarter(2017, 3)
>>> b.start
FiscalDateTime(2017, 4, 1, 0, 0)
>>> b.end
FiscalDateTime(2017, 6, 30, 23, 59, 59)
>>> a.q3 == b
True
>>> b in a
True
>>> b.next_fiscal_quarter
FiscalQuarter(2017, 4)
You can also get the current ``FiscalQuarter`` with:
.. code-block:: python
>>> FiscalQuarter.current()
FiscalQuarter(2018, 2)
FiscalMonth
-----------
The ``FiscalMonth`` class allows you to keep track of the fiscal month.
.. code-block:: python
>>> c = FiscalMonth(2017, 9)
>>> c.start
FiscalDateTime(2017, 6, 1, 0, 0)
>>> c.end
FiscalDateTime(2017, 6, 30, 23, 59, 59)
>>> c in a
True
>>> c in b
True
>>> c.next_fiscal_month
FiscalMonth(2017, 10)
You can also get the current ``FiscalMonth`` with:
.. code-block:: python
>>> FiscalMonth.current()
FiscalMonth(2018, 4)
FiscalDay
---------
To keep track of the fiscal day, use the ``FiscalDay`` class.
.. code-block:: python
>>> d = FiscalDay(2017, 250)
>>> d.start
FiscalDateTime(2017, 6, 6, 0, 0)
>>> d.end
FiscalDateTime(2017, 6, 6, 23, 59, 59)
>>> d in a
True
>>> d in b
True
>>> d in c
True
>>> d.next_fiscal_day
FiscalDay(2017, 251)
You can also get the current ``FiscalDay`` with:
.. code-block:: python
>>> FiscalDay.current()
FiscalDay(2018, 94)
FiscalDateTime
--------------
The start and end of each of the above objects are stored as instances of the ``FiscalDateTime`` class. This class provides all of the same features as the ``datetime`` class, with the addition of the ability to query the fiscal year, fiscal quarter, fiscal month, and fiscal day.
.. code-block:: python
>>> e = FiscalDateTime.now()
>>> e
FiscalDateTime(2017, 4, 8, 20, 30, 31, 105323)
>>> e.fiscal_year
2017
>>> e.fiscal_quarter
3
>>> e.next_fiscal_quarter
FiscalQuarter(2017, 4)
>>> e.fiscal_month
7
>>> e.fiscal_day
190
FiscalDate
----------
If you don't care about the time component of the ``FiscalDateTime`` class, the ``FiscalDate`` class is right for you.
.. code-block:: python
>>> f = FiscalDate.today()
>>> f
FiscalDate(2017, 4, 8)
>>> f.fiscal_year
2017
>>> f.prev_fiscal_year
FiscalYear(2016)
Installation
============
``fiscalyear`` has no dependencies, making it simple and easy to install. The recommended way to install ``fiscalyear`` is with ``pip``.
.. code-block:: console
$ pip install fiscalyear
For alternate installation methods, see the `Installation Documentation <http://fiscalyear.readthedocs.io/en/latest/installation.html>`_.
Documentation
=============
Documentation is hosted on `Read the Docs <http://fiscalyear.readthedocs.io/en/latest/index.html>`_.