Merge pull request #20 from DCMLab/develop

merge new version (0.4.0) from develop

Author: robert-lieck

.github/workflows/test_develop.yml

@@ -16,7 +16,7 @@ jobs:
     runs-on: ubuntu-latest
     strategy:
       matrix:
-        python-version: [3.6, 3.7, 3.8, 3.9]
+        python-version: ["3.7", "3.8", "3.9", "3.10"]
 
     steps:
     - uses: actions/checkout@v2

.github/workflows/tests.yml

@@ -15,7 +15,7 @@ jobs:
     runs-on: ubuntu-latest
     strategy:
       matrix:
-        python-version: [3.6, 3.7, 3.8, 3.9]
+        python-version: ["3.7", "3.8", "3.9", "3.10"]
 
     steps:
     - uses: actions/checkout@v2

.gitignore

@@ -70,6 +70,7 @@ instance/
 
 # Sphinx documentation
 docs/_build/
+docs/_autosummary/
 
 # PyBuilder
 target/

CHANGELOG.md

@@ -0,0 +1,35 @@
+# Changes
+
+## v0.4.0
+
+### new features
+
+- implement spelled array types
+  - vectorized operations (using numpy)
+  - supports array interface (indexing, iteration, etc.)
+- add one-hot encoding/decoding for all spelled types
+
+### breaking changes
+
+- update definition of "direction" on spelled types
+  - now altered unisons have a direction (except the perfect unison) for spelled types
+  - `d1:0` is now normalized to `-a1:0` (because `d1:0` is considered downward)
+  - compliant with the other libraries
+- remove `generic` and `diatonic_steps` from spelled pitch types
+  - both don't make sense (conceptually) for pitches
+  - potentially leak the underlying interval representation
+  - only degree is meaningful for pitches
+
+### improvements
+
+- better docstring formatting (parameters and return values)
+
+### bug fixes
+
+- implement ordering for spelled types in a consistent way
+  - add docs
+  - fixes bug where `Cb-1 > C-1` was true
+
+## v0.3.0
+
+first version that is compliant with the other libraries

README.md

@@ -20,7 +20,8 @@ For other (and mostly compatible) implementations see:
 
 The main goals of this library are:
 
-- providing types and operations (such as arithmetics, printing and parsing) for common types of pitches and intervals
+- providing types and operations (such as arithmetics, printing and parsing) for common types of pitches and intervals,
+  (in particular spelled pitches and intervals, which are often difficult to handle),
 - providing a generic interface for writing code that is agnostic to the specific pitch or interval types.
 
 ## Installation

docs/_templates/custom-class-template.rst

@@ -0,0 +1,34 @@
+{{ fullname | escape | underline}}
+
+.. currentmodule:: {{ module }}
+
+.. autoclass:: {{ objname }}
+   :members:
+   :show-inheritance:
+   :inherited-members:
+   :special-members:
+   :exclude-members: __init__
+
+   {% block methods %}
+   .. automethod:: __init__
+
+   {% if methods %}
+   .. rubric:: {{ _('Methods') }}
+
+   .. autosummary::
+   {% for item in methods %}
+      ~{{ name }}.{{ item }}
+   {%- endfor %}
+   {% endif %}
+   {% endblock %}
+
+   {% block attributes %}
+   {% if attributes %}
+   .. rubric:: {{ _('Attributes') }}
+
+   .. autosummary::
+   {% for item in attributes %}
+      ~{{ name }}.{{ item }}
+   {%- endfor %}
+   {% endif %}
+   {% endblock %}

docs/_templates/custom-module-template.rst

@@ -0,0 +1,66 @@
+{{ fullname | escape | underline}}
+
+.. automodule:: {{ fullname }}
+
+   {% block attributes %}
+   {% if attributes %}
+   .. rubric:: Module Attributes
+
+   .. autosummary::
+      :toctree:
+   {% for item in attributes %}
+      {{ item }}
+   {%- endfor %}
+   {% endif %}
+   {% endblock %}
+
+   {% block functions %}
+   {% if functions %}
+   .. rubric:: {{ _('Functions') }}
+
+   .. autosummary::
+      :toctree:
+   {% for item in functions %}
+      {{ item }}
+   {%- endfor %}
+   {% endif %}
+   {% endblock %}
+
+   {% block classes %}
+   {% if classes %}
+   .. rubric:: {{ _('Classes') }}
+
+   .. autosummary::
+      :toctree:
+      :template: custom-class-template.rst
+   {% for item in classes %}
+      {{ item }}
+   {%- endfor %}
+   {% endif %}
+   {% endblock %}
+
+   {% block exceptions %}
+   {% if exceptions %}
+   .. rubric:: {{ _('Exceptions') }}
+
+   .. autosummary::
+      :toctree:
+   {% for item in exceptions %}
+      {{ item }}
+   {%- endfor %}
+   {% endif %}
+   {% endblock %}
+
+{% block modules %}
+{% if modules %}
+.. rubric:: Modules
+
+.. autosummary::
+   :toctree:
+   :template: custom-module-template.rst
+   :recursive:
+{% for item in modules %}
+   {{ item }}
+{%- endfor %}
+{% endif %}
+{% endblock %}

docs/api_summary.rst

@@ -0,0 +1,10 @@
+API Summary
+=====================
+
+
+.. autosummary::
+   :toctree: _autosummary
+   :template: custom-module-template.rst
+   :recursive:
+
+   pitchtypes

docs/conf.py

@@ -31,6 +31,8 @@
     'myst_parser',
     'sphinx.ext.autodoc',
     'sphinx.ext.doctest',
+    'sphinx.ext.autosummary',
+    'sphinx_autodoc_typehints',
 ]
 
 # Add any paths that contain templates here, relative to this directory.
@@ -53,3 +55,6 @@
 # relative to this directory. They are copied after the builtin static files,
 # so a file named "default.css" will overwrite the builtin "default.css".
 html_static_path = ['_static']
+
+# sort class members by type
+# autodoc_member_order = 'bysource'

docs/index.rst

@@ -12,9 +12,11 @@ Welcome to pitchtypes's documentation!
 
    introduction
    types/spelled
+   types/spelled_array
    types/enharmonic
    types/frequencies
    types/harmonic
+   api_summary
 
 
 A library for **handling musical pitches and intervals in a systematic way**.
@@ -29,15 +31,15 @@ Arithmetics
 -----------
 
 You can, for instance, compute the interval class between a B♭ and an F♯,
-which is an augmented fifth
+which is an augmented fifth:
 
 .. doctest::
 
    >>> import pitchtypes as pt
    >>> pt.SpelledPitchClass("F#") - pt.SpelledPitchClass("Bb")
    a5
 
-and do all the standard arithmetic operations.
+You can also perform all sensible arithmetic operations on intervals and pitches.
 
 Generic Interface
 -----------------