Merge branch 'release/0.6.0'

.github/workflows/ci.yml

@@ -21,11 +21,11 @@ jobs:
         os: [ubuntu-latest, windows-latest, macos-latest]
         python-version: ["3.8", "3.9", "3.10", "3.11"]
     steps:
-    - uses: actions/checkout@v3
+    - uses: actions/checkout@v4
     - name: Install poetry
       run: pipx install poetry
     - name: Set up Python ${{ matrix.python-version }}
-      uses: actions/setup-python@v4
+      uses: actions/setup-python@v5
       with:
         python-version: ${{ matrix.python-version }}
         cache: 'poetry'

.github/workflows/publish-rc.yml

@@ -8,7 +8,7 @@ on:
       - 'support/**'
 
 env:
-  PACKAGE_NAME: exchange_calendars_extensions
+  PACKAGE_NAME: exchange-calendars-extensions
   MODULE_NAME: exchange_calendars_extensions.core
 
 jobs:
@@ -18,11 +18,11 @@ jobs:
     permissions:
       id-token: write
     steps:
-    - uses: actions/checkout@v3
+    - uses: actions/checkout@v4
     - name: Install poetry.
       run: pipx install poetry
     - name: Set up Python.
-      uses: actions/setup-python@v4
+      uses: actions/setup-python@v5
       with:
         python-version: "3.11"
         cache: 'poetry'

.github/workflows/publish.yml

@@ -15,11 +15,11 @@ jobs:
     permissions:
       id-token: write
     steps:
-    - uses: actions/checkout@v3
+    - uses: actions/checkout@v4
     - name: Install poetry.
       run: pipx install poetry
     - name: Set up Python.
-      uses: actions/setup-python@v4
+      uses: actions/setup-python@v5
       with:
         python-version: "3.11"
         cache: 'poetry'

docs/_index.md

@@ -0,0 +1,65 @@
+---
+title: "Introduction"
+draft: false
+type: docs
+layout: "single"
+
+menu:
+  docs_extensions:
+      weight: 0
+---
+# Introduction
+The `exchange-calendars-extensions` Python package transparently adds some features to the `exchange-calendars` package. 
+It can be used without any changes to existing code that already uses [`exchange-calendars`](https://example.com).
+
+## System requirements
+The package requires Python 3.8 or later.
+
+## Installation
+The package is available on [PyPI](https://pypi.org/project/exchange-calendars-extensions/) and can be installed via 
+[pip](https://pip.pypa.io/en/stable/) or any other suitable package/dependency management tool, e.g. 
+[Poetry](https://python-poetry.org/).
+
+{{< tabs tabTotal="2" tabID1="installing-with-pip" tabID2="installing-with-poetry" tabName1="With pip" tabName2="With Poetry">}}
+
+{{< tab tabID="installing-with-pip" >}}
+
+{{< steps >}}
+{{< step >}}
+**Install**
+
+```bash
+pip install exchange-calendars-extensions
+```
+{{< /step >}}
+{{< step >}}
+**Install (advanced)**
+
+You can pin to a specific package version. For example, to install version 1.0:
+
+```bash
+pip install exchange-calendars-extensions==1.0
+```
+{{< /step >}}
+{{< step >}}
+**Uninstall**
+
+```bash
+pip uninstall exchange-calendars-extensions
+```
+{{< /step >}}
+{{< /steps >}}
+
+{{< /tab >}}
+{{< tab tabID="installing-with-poetry" >}}
+To add the package to a project managed with Poetry, add it to the project's `pyproject.toml` file:
+
+```toml
+[tool.poetry.dependencies]
+exchange-calendars-extensions = "^1.0"
+```
+
+Then, run `poetry install` to install the package.
+
+{{< /tab >}}
+{{< /tabs >}}

docs/additional_calendars.md

@@ -0,0 +1,85 @@
+---
+title: "Additional Calendars"
+draft: false
+type: docs
+layout: "single"
+
+menu:
+  docs_extensions:
+      weight: 40
+---
+# Additional Calendars
+
+Extended exchange calendars provide additional calendars for special trading sessions and non-business days.
+
+## Quarterly Expiry Days
+
+Quarterly expiry days are also known as *triple* or *quadruple witching* days. They represent special trading sessions 
+when stock index futures, stock index options, stock options and single stock futures expire.
+
+On many exchanges, these sessions take place on the third Friday in March, June, September and December. However, some 
+exchanges deviate from this pattern. For example, Johannesburg Stock Exchange (XJSE) has quarterly expiry days on the 
+third Thursday in those months. Also, quarterly expiry days are currently only supported for a limited number of 
+exchanges.
+
+{{% note title="Supported exchanges for expiry day sessions" collapsible="true" %}}
+Calendars for expiry day sessions are currently only available for the following exchanges:
+{{% autocolumns %}}
+- ASEX
+- BMEX
+- XAMS
+- XBRU
+- XBUD
+- XCSE
+- XDUB
+- XETR
+- XHEL
+- XIST
+- XJSE
+- XLIS
+- XLON
+- XMAD
+- XMIL
+- XNAS
+- XNYS
+- XOSL
+- XPAR
+- XPRA
+- XSTO
+- XSWX
+- XTAE
+- XTSE
+- XWAR
+- XWBO
+{{% /autocolumns %}}
+{{% /note %}}
+
+Quarterly expiry trading sessions often differ from regular trading sessions owing to increased volatility and trading 
+volume. Many exchanges have their own specific rules for these sessions, so some characteristics of these sessions may
+be different. For example, the London Stock Exchange (XLON) uses an additional *Exchange Delivery Settlement Price 
+(EDSP)* auction to determine the reference price for the settlement of derivatives contracts. Other exchanges may use
+regular scheduled opening or closing auctions for the same purpose.
+
+{{% note %}}
+Modelling the precise characteristics of quarterly expiry trading sessions, beyond providing a calendar, is beyond the 
+scope of `exchange-calendars-extensions`.
+{{% /note %}}
+
+Here is an example for the quarterly expiry days of the London Stock Exchange (XLON):
+```python
+import exchange_calendars_extensions.core as ecx
+import exchange_calendars as ec
+
+ecx.apply_extensions()
+
+calendar = ec.get_calendar('XLON')
+print(calendar.quarterly_expiries.holidays(start='2023-01-01', end='2023-12-31', return_name=True))
+```
+This gives the following output:
+```text
+2023-03-17    quarterly expiry
+2023-06-16    quarterly expiry
+2023-09-15    quarterly expiry
+2023-12-15    quarterly expiry
+dtype: object
+```

docs/basic_usage.md

@@ -0,0 +1,71 @@
+---
+title: "Basic Usage"
+draft: false
+type: docs
+layout: "single"
+
+menu:
+  docs_extensions:
+      weight: 20
+---
+# Basic Usage
+To use the extensions, import the top-level module and register the extended exchange calendar classes.
+```python
+import exchange_calendars_extensions.core as ecx
+
+# Apply extensions.
+ecx.apply_extensions()
+```
+This replaces the default calendar classes in `exchange_calendars` with the extended versions. You can now use these
+extended classes while existing code should continue to work as before.
+
+## Extended Exchange Calendars
+
+```python
+import exchange_calendars_extensions.core as ecx
+import exchange_calendars as ec
+
+ecx.apply_extensions()
+
+# Get an exchange calendar instance.
+calendar = ec.get_calendar('XLON')
+
+# It's still a regular exchange calendar.
+assert isinstance(calendar, ec.ExchangeCalendar)
+
+# But it's also an extended exchange calendar...
+assert isinstance(calendar, ecx.ExtendedExchangeCalendar)
+
+# ...that implements a protocol that defines additional properties.
+assert isinstance(calendar, ecx.ExchangeCalendarExtensions)
+```
+
+{{% note %}}
+The class `ecx.ExtendedExchangeCalendar` is an abstract base class that inherits from `ec.ExchangeCalendar` and the 
+protocol class `ecx.ExchangeCalendarExtensions` which defines the extended properties.
+{{% /note %}}
+
+
+## Removing Extensions
+
+In the unlikely case that you later need to re-instate the original classes, you can do so:
+
+```python
+import exchange_calendars_extensions.core as ecx
+import exchange_calendars as ec
+
+ecx.apply_extensions()
+
+...
+
+ecx.remove_extensions()
+
+calendar = ec.get_calendar('XLON')
+
+# It's a regular exchange calendar.
+assert isinstance(calendar, ec.ExchangeCalendar)
+
+# But it's not an extended exchange calendar anymore.
+assert not isinstance(calendar, ecx.ExtendedExchangeCalendar)
+assert not isinstance(calendar, ecx.ExchangeCalendarExtensions)
+```