141 lines
4.5 KiB
Markdown
141 lines
4.5 KiB
Markdown
# FixedCal
|
|
|
|
[](https://github.com/PyryL/fixedcal/actions)
|
|
[](https://codecov.io/gh/PyryL/fixedcal)
|
|
[](LICENSE)
|
|
|
|
Python package for international fixed calendar dates.
|
|
|
|
## What is that?
|
|
|
|
International fixed calendar is an alternative calendar system.
|
|
It divides year into 13 even months by adding a month called Sol between June and July.
|
|
Each month starts with Sunday and has exactly 28 days or 4 weeks.
|
|
An additional _year day_ is added to the end of the year and it does not belong to any of the months and has no weekday.
|
|
You can read more about IFC on [Wikipedia](https://en.wikipedia.org/wiki/International_Fixed_Calendar).
|
|
|
|
## Installation
|
|
|
|
This package is available via PyPI:
|
|
|
|
```
|
|
pip install fixedcal
|
|
```
|
|
|
|
You can also download the package directly from [releases](https://github.com/PyryL/fixedcal/releases).
|
|
|
|
## Usage
|
|
|
|
### Date initialization
|
|
|
|
```python3
|
|
from fixedcal import FixedDate
|
|
|
|
# Date of today
|
|
fixed_date = FixedDate.today()
|
|
|
|
# From native datetime
|
|
import datetime
|
|
february_seventh = datetime.date(2022, 2, 7)
|
|
fixed_date = FixedDate(february_seventh)
|
|
|
|
# From fixed day of month, month and year
|
|
fixed_date = FixedDate(day=24, month=4, year=2022)
|
|
|
|
# From day's ordinal in year
|
|
fixed_date = FixedDate(day_of_year=107, year=2022)
|
|
```
|
|
|
|
### Date's properties
|
|
|
|
```python3
|
|
from fixedcal import FixedDate
|
|
import datetime
|
|
fixed_date = FixedDate(datetime.date(2022, 8, 12))
|
|
|
|
fixed_date.date # datetime.date(2022, 8, 12)
|
|
fixed_date.day_of_year # 224
|
|
fixed_date.day_of_month # 28
|
|
fixed_date.month # 8
|
|
fixed_date.year # 2022
|
|
fixed_date.is_year_day # False
|
|
fixed_date.is_leap_day # False
|
|
fixed_date.is_leap_year # False
|
|
fixed_date.week_of_month # 4
|
|
fixed_date.weekday # 7
|
|
fixed_date.week_of_year # 32
|
|
fixed_date.year_quarter # 3
|
|
```
|
|
|
|
### Date's operations
|
|
|
|
```python3
|
|
from fixedcal import FixedDate
|
|
from datetime import date, timedelta
|
|
|
|
fixed_date = FixedDate(date(2022, 12, 6))
|
|
jan_first = FixedDate(date(2023, 1, 1))
|
|
|
|
str(fixed_date) # 2022-13-04
|
|
|
|
new_fixed = fixed_date + timedelta(3) # FixedDate 3 days ahead
|
|
new_fixed = fixed_date - timedelta(2) # FixedDate 2 days before
|
|
new_fixed = jan_first - fixed_date # timedelta between dates
|
|
|
|
fixed_date == fixed_date # True
|
|
fixed_date != jan_first # True
|
|
jan_first < fixed_date # False
|
|
```
|
|
|
|
### Year day
|
|
|
|
Year day is the day after the last of December and before the first of January.
|
|
For that date, `FixedDate` gives the following property values.
|
|
|
|
* `day_of_year` = 365 (366 on leap years)
|
|
* `day_of_month` = 29
|
|
* `month` = 13
|
|
* `year` is obviously the ending year
|
|
* `is_year_day` = True
|
|
* `week_of_month` = 4
|
|
* `weekday` = None
|
|
* `week_of_year` = 52
|
|
* `year_quarter` = 4
|
|
|
|
### Leap day
|
|
|
|
Leap day occurres on the same years as in Gregorian calendar. However, the placement of that day is different: after the last day of June and before the first day of Sol (17th June in Gregorian). The following properties are given by `FixedDate` for leap day:
|
|
|
|
* `day_of_year` = 169
|
|
* `day_of_month` = 29
|
|
* `month` = 6
|
|
* `is_leap_day` = True
|
|
* `is_leap_year` = True
|
|
* `week_of_month` = 4
|
|
* `weekday` = None
|
|
* `week_of_year` = 24
|
|
* `year_quarter` = 2
|
|
|
|
## Contributing
|
|
|
|
Yes, you can contribute in the development of this package. If you find a bug or have a feature request, please file an [issue](https://github.com/PyryL/fixedcal/issues/new). You can also modify the code yourself and create a pull request.
|
|
|
|
You need [Poetry](https://python-poetry.org/) to manage the development environment. After downloading the source code of this package, run `poetry install` to install development dependencies and to set up a compatible Python environment.
|
|
|
|
During development you can use the following commands:
|
|
|
|
```
|
|
poetry run invoke test
|
|
poetry run invoke lint
|
|
poetry run invoke coverage
|
|
poetry run invoke clean
|
|
poetry run invoke build
|
|
poetry run invoke publish
|
|
```
|
|
|
|
Please check the following topics before creating a pull request:
|
|
|
|
* Your changes should not create new Pylint errors.
|
|
* There should be proper unit tests included in the pull request. This consists of high branch coverage (>90%) and quality of the tests. Working with dates has a lot of corner cases and tests are the best way to avoid bugs.
|
|
* The structure of the project should remain healthy: split the code between modules and packages.
|