datetime-month 1.0.6
a package that handles months.
License: MIT license
Requires Python: >=3.6
Keywords: month,date

=====
month
=====


.. image:: https://img.shields.io/pypi/v/datetime-month.svg
        :target: https://pypi.python.org/pypi/datetime-month

..  image:: https://github.com/yitistica/month/actions/workflows/pre-release-test.yml/badge.svg
        :target: https://github.com/yitistica/month/actions/workflows/pre-release-test.yml

..  image:: https://readthedocs.org/projects/month/badge/?version=latest
    :target: https://month.readthedocs.io/en/latest/?badge=latest
    :alt: Documentation Status


A package that handles calendar months and arithmetic operation of months.

The package comprises two modules: **month** and **x_month**.
**month** module provides the base classes for manipulating month-level time.
**x_month** module extends the base classes from the *month* module to include additional functionalities.


Installation
------------

.. code-block::

  pip install datetime-month


Features & Usage
----------------

To construct a month object:

.. code-block:: python

   from month import Month
   from month import XMonth  # extended month;

   m = Month(2020, 4)
   xm = XMonth(2020, 4)

Additional construction methods below can be used to translate a *tuple* (year, month), a *isoformat* string,
an *ordinal* int and *month-format* string into a **Month** object.

.. code-block:: python

   # constructed from a (year, month) tuple:
   m = Month.fromtuple((2019, 11))

   # isoformat is defined as a str in "year-month" format:
   m = Month.fromisoformat('2019-12')

   # ordinal (as in date units):
   m = Month.fromordinal(737390)

   # using string format like datetime:
   m = Month.strptime('2019/1', '%Y/%m')

For the representation of the difference between two months, we can use **Mdelta** (similar to *timedelta* in datetime modules). To construct:

.. code-block:: python

   from month import MDelta
   delta = Mdelta(2)  # Mdelta(months), months: int;

**Mdelta** supports comparisons using operators. It also supports some arithmetic operations (addition, subtraction, and multiplication)
among Mdelta objects or with Month objects or int objects.

.. code-block:: python

   Mdelta(2) < Mdelta(3)  # returns bool;
   Mdelta(2) - Mdelta(3)  # returns Mdelta(-1);
   Mdelta(2) * 2 # returns Mdelta(4);

Some arithmetic operations and comparisons are also supported for **Month** objects.

.. code-block:: python

   Month(2019, 11).add(MDelta(2)) # returns Month(2020, 1);
   Month(2020, 04) + Mdelta(2)  # returns Month(2020, 6);
   Month(2020, 1) - 2  # returns Month(2019, 11);
   Month(2020, 04) <= Month(2020, 06)  # returns True;

**XMonth** is an extended version of **Month** by including some convenient manipulation and sub-level operations.

.. code-block:: python

   xm = XMonth(2019, 11)

   xm.days()  # returns total days in the month;

   xm.first_date()  # returns date(2019,11,1)

   # iterate dates within the month in increment by step days:
   xm.dates(step=2)

   # iterate months in a given range:
   XMonth.range(starting_month, ending_month, step=1)

License
--------
* Free software: MIT license


Credits
-------
The repo was initiated using `audreyr/cookiecutter-pypackage`_ project template.

.. _`audreyr/cookiecutter-pypackage`: https://github.com/audreyr/cookiecutter-pypackage


=======
History
=======


0.1.0 (2020-03-21)
------------------

* First release on PyPI.

1.0.3 (2022-10-11)
------------------

* **FIX:** Fix wrong package metadata in setup - `#2`_.

.. _#2: https://github.com/yitistica/month/issues/2

1.0.4 (2022-11-10)
------------------

* **FIX:** Fix arithmetic operation on XMonth returning base class Month object instead of XMonth  - `#8`_. Contributed by `@ramwin <https://github.com/ramwin>`_. Thank you!

.. _#8: https://github.com/yitistica/month/pull/8

1.0.5 (2024-02-15)
------------------

* Add compatibility with Python 3.11 & 3.12.

1.0.6 (2024-02-15)
------------------

* Fix ReadMe note.