sofar 1.2.0__tar.gz → 1.2.1__tar.gz

{sofar-1.2.0 → sofar-1.2.1}/CONTRIBUTING.rst

@@ -45,14 +45,12 @@ Ready to contribute? Here's how to set up `sofar` for local development using th
 3. Note that some graphical Git interfaces can not do the recursive clone. If the folder sofar/sofa_conventions is empty try::
 
     $ git submodule update --init
-
+    
 4. Install your local copy into a virtualenv. Assuming you have Anaconda or Miniconda installed, this is how you set up your fork for local development::
 
     $ conda create --name sofar python
     $ conda activate sofar
-    $ conda install pip
-    $ pip install -e .
-    $ pip install -r requirements_dev.txt
+    $ pip install -e ".[dev]"
 
 5. Create a branch for local development. Indicate the intention of your branch in its respective name (i.e. `feature/branch-name` or `bugfix/branch-name`)::
 

{sofar-1.2.0 → sofar-1.2.1}/HISTORY.rst

@@ -2,6 +2,10 @@
 History
 =======
 
+1.2.1 (2024-12-12)
+------------------
+* Deployment: Move from setup.py to pyproject.toml (PR #114, #115)
+
 1.2.0 (2024-08-29)
 ------------------
 * Feature: Introduce `SofaStream` class for reading parts of large Sofa files without reading the entire file (PR #90, 97)

{sofar-1.2.0 → sofar-1.2.1}/PKG-INFO

@@ -1,16 +1,38 @@
 Metadata-Version: 2.1
 Name: sofar
-Version: 1.2.0
-Summary: Maybe the most complete python package for SOFA files so far
-Home-page: https://pyfar.org/
-Download-URL: https://pypi.org/project/sofar/
-Author: The pyfar developers
-Author-email: info@pyfar.org
-License: MIT license
-Project-URL: Bug Tracker, https://github.com/pyfar/sofar/issues
+Version: 1.2.1
+Summary: Maybe the most complete python package for SOFA files so far.
+Author-email: The pyfar developers <info@pyfar.org>
+License: MIT License
+        
+        Copyright (c) 2021, The pyfar developers
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+        
+        
+Project-URL: Tracker, https://github.com/pyfar/sofar/issues
 Project-URL: Documentation, https://sofar.readthedocs.io/
-Project-URL: Source Code, https://github.com/pyfar/sofar
-Keywords: sofar
+Project-URL: Download, https://pypi.org/project/sofar/
+Project-URL: Homepage, https://pyfar.org/
+Project-URL: Source, https://github.com/pyfar/sofar
+Project-URL: Changelog, https://github.com/pyfar/sofar/blob/main/HISTORY.rst
+Keywords: acoustics,pyfar
 Classifier: Development Status :: 4 - Beta
 Classifier: Intended Audience :: Science/Research
 Classifier: License :: OSI Approved :: MIT License
@@ -24,12 +46,32 @@ Classifier: Programming Language :: Python :: 3.12
 Requires-Python: >=3.8
 Description-Content-Type: text/markdown
 License-File: LICENSE
-License-File: AUTHORS.rst
 Requires-Dist: netCDF4
 Requires-Dist: numpy>=1.14.0
 Requires-Dist: beautifulsoup4
 Requires-Dist: requests
-Requires-Dist: packaging
+Provides-Extra: deploy
+Requires-Dist: twine; extra == "deploy"
+Requires-Dist: wheel; extra == "deploy"
+Requires-Dist: build; extra == "deploy"
+Requires-Dist: setuptools; extra == "deploy"
+Requires-Dist: bump-my-version; extra == "deploy"
+Provides-Extra: tests
+Requires-Dist: pytest; extra == "tests"
+Requires-Dist: pytest-cov; extra == "tests"
+Requires-Dist: watchdog; extra == "tests"
+Requires-Dist: ruff==0.8.2; extra == "tests"
+Requires-Dist: coverage; extra == "tests"
+Provides-Extra: docs
+Requires-Dist: sphinx; extra == "docs"
+Requires-Dist: autodocsumm>=0.2.14; extra == "docs"
+Requires-Dist: pydata-sphinx-theme; extra == "docs"
+Requires-Dist: sphinx_mdinclude; extra == "docs"
+Requires-Dist: sphinx-design; extra == "docs"
+Requires-Dist: sphinx-favicon; extra == "docs"
+Requires-Dist: sphinx-reredirects; extra == "docs"
+Provides-Extra: dev
+Requires-Dist: sofar[deploy,docs,tests]; extra == "dev"
 
 <h1 align="center">
 <img src="https://github.com/pyfar/gallery/raw/main/docs/resources/logos/pyfar_logos_fixed_size_sofar.png" width="300">
@@ -38,6 +80,7 @@ Requires-Dist: packaging
 [![PyPI version](https://badge.fury.io/py/sofar.svg)](https://badge.fury.io/py/sofar)
 [![Documentation Status](https://readthedocs.org/projects/sofar/badge/?version=latest)](https://sofar.readthedocs.io/en/latest/?badge=latest)
 [![CircleCI](https://circleci.com/gh/pyfar/sofar.svg?style=shield)](https://circleci.com/gh/pyfar/sofar)
+[![Binder](https://mybinder.org/badge_logo.svg)](https://mybinder.org/v2/gh/pyfar/gallery/main?labpath=docs/gallery/interactive/sofar_introduction.ipynb)
 
 Sofar is maybe the most complete Python package for the SOFA file format so
 far. SOFA files store spatially distributed acoustic data such as impulse

{sofar-1.2.0 → sofar-1.2.1}/README.md

@@ -5,6 +5,7 @@
 [![PyPI version](https://badge.fury.io/py/sofar.svg)](https://badge.fury.io/py/sofar)
 [![Documentation Status](https://readthedocs.org/projects/sofar/badge/?version=latest)](https://sofar.readthedocs.io/en/latest/?badge=latest)
 [![CircleCI](https://circleci.com/gh/pyfar/sofar.svg?style=shield)](https://circleci.com/gh/pyfar/sofar)
+[![Binder](https://mybinder.org/badge_logo.svg)](https://mybinder.org/v2/gh/pyfar/gallery/main?labpath=docs/gallery/interactive/sofar_introduction.ipynb)
 
 Sofar is maybe the most complete Python package for the SOFA file format so
 far. SOFA files store spatially distributed acoustic data such as impulse

{sofar-1.2.0 → sofar-1.2.1}/docs/conf.py

@@ -12,8 +12,8 @@ import urllib3
 import shutil
 sys.path.insert(0, os.path.abspath('..'))
 
-import sofar  # noqa
-import resources.conventions  # noqa: build conventions for documentation
+import sofar
+import resources.conventions
 
 # -- General configuration ---------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
@@ -130,6 +130,8 @@ html_theme_options = {
     "show_toc_level": 3,  # Show all subsections of notebooks
     "secondary_sidebar_items": ["page-toc"],  # Omit 'show source' link that that shows notebook in json format
     "navigation_with_keys": True,
+    # Configure navigation depth for section navigation
+    "navigation_depth": 1,
 }
 
 html_context = {

sofar-1.2.1/docs/resources/conventions.py

@@ -0,0 +1,162 @@
+import os
+import sys
+import json
+sys.path.insert(0, os.path.abspath(os.path.join('..', '..')))
+
+import sofar as sf
+
+base_dir = os.path.dirname(__file__)
+
+# get conventions (paths, names, version) and upgrade rules -------------------
+paths = sf.utils._get_conventions('path')
+names_versions = sf.utils._get_conventions('name_version')
+
+# using Sofa()._verification_rules() does not work on readthedocs
+upgrade_rules = os.path.join(
+    os.path.dirname(paths[0]), '..', 'rules', 'upgrade.json')
+with open(upgrade_rules) as file:
+    upgrade_rules = json.load(file)
+
+deprecation_rules = os.path.join(
+    os.path.dirname(paths[0]), '..', 'rules', 'deprecations.json')
+with open(deprecation_rules) as file:
+    deprecation_rules = json.load(file)
+
+# write general information ---------------------------------------------------
+docs = (
+    '.. _conventions_introduction:\n\n'
+    'SOFA Conventions\n'
+    '================\n\n'
+    'SOFA conventions specify what data and metadata must be stored in a SOFA '
+    'file. Different conventions can be used to store different types of data,'
+    'e.g., head-related impulse responses or musical instrument directivities.'
+    'It is advised to always use the conventions that is most specific for the'
+    'data.\n\n'
+    'In the following, SOFA conventions are described in tables with the '
+    'information\n\n'
+    '* **Name:** The Name of the data. The prefix *GLOBAL* denotes global '
+    'attribute, i.e., attributes that pertain the entire data set. Underscores'
+    ' denote attributes that are data specific. E.g., *SourcePosition_Units* '
+    'denotes the *Units* of the data *SourcePosition*.\n'
+    '* **Type:** The Type of the data.\n\n'
+    '  * **Attribute:** A verbose description given by a string\n'
+    '  * **Double:** A numeric array of data\n'
+    '  * **String:** A string array of data\n\n'
+    '* **Default:** The default value\n'
+    '* **Dimensions:** The dimensions of the data. Lower case letters denote '
+    'the data that sets the dimension.\n\n'
+    '  * **E:** Number of emitters\n'
+    '  * **R:** Number of receivers\n'
+    '  * **M:** Number of measurements\n'
+    '  * **N:** Number of samples or frequency bins of the data\n'
+    '  * **C:** Number of coordinates (always 3)\n'
+    '  * **I:** Unity dimensions (always 1)\n'
+    '  * **S:** Lengths of the longest string contained in the data '
+    '(detected automatically)\n\n'
+    '* **Flags:**\n\n'
+    '  * **r:** read only data. Data can be written if flag is missing.\n'
+    '  * **m:** mandatory data. Data is optional if flag is missing\n\n')
+
+# write table of content ------------------------------------------------------
+docs += '.. _conventions:\n\nConventions\n-----------\n\n'
+for path, name_version in zip(paths, names_versions):
+    name, version = name_version
+
+    label = f'{name} v{version}'
+    if 'deprecated' in path:
+        label += ' (deprecated)'
+    reference = f'{name}_{version}'
+
+    docs += f'* :ref:`{label} <{reference}>`\n'
+
+# write conventions -----------------------------------------------------------
+docs += '\nCurrent\n-------\n\n'
+
+# loop conventions
+deprecated = False
+for path, name_version in zip(paths, names_versions):
+    name, version = name_version
+
+    # read convention from json file
+    with open(path, 'r') as file:
+        convention = json.load(file)
+
+    # write section title
+    if 'deprecated' in path and not deprecated:
+        docs += 'Deprecated\n----------\n\n'
+        deprecated = True
+
+    # write convention name, version
+    docs += f'.. _{name}_{version}:\n\n'
+    docs += f'**{name} v{version}**\n\n'
+
+    # name new convention if current convention is deprecated
+    if deprecated:
+        # upgrade rules give best feedback
+        if name in upgrade_rules:
+            for upgrade in upgrade_rules[name]['from_to']:
+                if version in upgrade[0]:
+                    upgrade_to = upgrade[1]
+                    references = [f':ref:`{u} <{u}>`' for u in upgrade_to]
+                    ':ref:`{label} <{reference}>`'
+                    docs += ('This convention is deprecated. '
+                             f'Use {", ".join(references)} instead.\n\n')
+        # deprecations are used if no upgrade rules are available
+        elif name in deprecation_rules['GLOBAL:SOFAConventions']:
+            docs += ("This convention is deprecated. Use "
+                     f"{deprecation_rules['GLOBAL:SOFAConventions'][name]} "
+                     "instead.\n\n")
+
+    # name purpose of the convention
+    docs += f'{convention["GLOBAL:SOFAConventions"]["comment"]}\n\n'
+
+    # write header
+    docs += (
+        '.. list-table::\n'
+        '   :widths: 20 50 25 30 100\n'
+        '   :header-rows: 1\n\n'
+        '   * - Name (Type)\n'
+        '     - Default\n'
+        '     - Dim.\n'
+        '     - Flags\n'
+        '     - Comment\n')
+
+    # loop entries
+    for key, value in convention.items():
+
+        if value["dimensions"] is None:
+            dimensions = ""
+        else:
+            dimensions = value["dimensions"]
+
+        if value["flags"] is None:
+            flags = ""
+        elif len(value["flags"]) > 1:
+            flags = f'{value["flags"][0]}, {value["flags"][1]}'
+        else:
+            flags = value["flags"]
+
+        if key == "GLOBAL:SOFAConventions":
+            value["comment"] = ""
+
+        if value["type"] == 'attribute':
+            type_str = 'attr.'
+        elif value["type"] == 'double':
+            type_str = 'doub.'
+        else:
+            type_str = 'str.'
+
+        docs += (
+            f'   * - {key.replace(":", "_").replace(".", "_")} '
+            f'(*{value["type"]}*)\n'
+            f'     - {value["default"]}\n'
+            f'     - {dimensions}\n'
+            f'     - {flags}\n'
+            f'     - {value["comment"]}\n')
+
+    docs += '\n:ref:`back to top <conventions>`\n\n'
+
+# write docs to rst file ------------------------------------------------------
+docs_file = os.path.join(base_dir, 'conventions.rst')
+with open(docs_file, 'w') as file:
+    file.writelines(docs)

sofar-1.2.1/pyproject.toml

@@ -0,0 +1,154 @@
+[project]
+name = "sofar"
+version = "1.2.1"
+description = "Maybe the most complete python package for SOFA files so far."
+readme = "README.md"
+license = {file = "LICENSE"}
+requires-python = ">=3.8"
+authors = [
+    { name = "The pyfar developers", email = "info@pyfar.org" },
+]
+keywords = [
+    "acoustics",
+    "pyfar",
+]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Science/Research",
+    "License :: OSI Approved :: MIT License",
+    "Natural Language :: English",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.8",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+]
+dependencies = [
+    'netCDF4',
+    'numpy>=1.14.0',
+    'beautifulsoup4',
+    'requests',
+]
+
+[project.optional-dependencies]
+deploy = [
+    "twine",
+    "wheel",
+    "build",
+    "setuptools",
+    "bump-my-version",
+    ]
+tests = [
+    "pytest",
+    "pytest-cov",
+    "watchdog",
+    "ruff==0.8.2",
+    "coverage",
+]
+docs = [
+    "sphinx",
+    "autodocsumm>=0.2.14",
+    "pydata-sphinx-theme",
+    "sphinx_mdinclude",
+    "sphinx-design",
+    "sphinx-favicon",
+    "sphinx-reredirects",
+]
+dev = ["sofar[deploy,tests,docs]"]
+
+[project.urls]
+Tracker = "https://github.com/pyfar/sofar/issues"
+Documentation = "https://sofar.readthedocs.io/"
+Download = "https://pypi.org/project/sofar/"
+Homepage = "https://pyfar.org/"
+Source = "https://github.com/pyfar/sofar"
+Changelog = "https://github.com/pyfar/sofar/blob/main/HISTORY.rst"
+
+[build-system]
+requires = ["setuptools>=61.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[tool.setuptools.packages]
+find = {}  # Scan the project directory with the default parameters
+
+
+[tool.ruff]
+exclude = [
+    ".git",
+    "docs",
+]
+line-length = 79
+lint.ignore = [
+    "D200",   # One-line docstring should fit on one line with quotes
+    "D202",   # No blank lines allowed after function docstring
+    "D205",   # 1 blank line required between summary line and description
+    "D401",   # First line should be in imperative mood
+    "D404",   # First word of the docstring should not be "This"
+    "B006",   # Do not use mutable data structures for argument defaults
+    "B008",   # Do not perform calls in argument defaults
+    "PT018",  # Assertion should be broken down into multiple parts
+    "PT019",  # Fixture `_` without value is injected as parameter
+]
+lint.select = [
+    "B",      # bugbear extension
+    "ARG",    # Remove unused function/method arguments
+    "C4",     # Check for common security issues
+    "E",      # PEP8 errors
+    "F",      # Pyflakes
+    "W",      # PEP8 warnings
+    "D",      # Docstring guidelines
+    "NPY",    # Check all numpy related deprecations
+    "D417",   # Missing argument descriptions in the docstring
+    "PT",     # Pytest style
+    "A",      # Avoid builtin function and type shadowing
+    "ERA",    # No commented out code
+    "NPY",    # Check all numpy related deprecations
+    "COM",    # trailing comma rules
+    "I002",   # missing required import
+    "TID252", # Use absolute over relative imports
+    "FIX",    # Code should not contain FIXME, TODO, etc
+]
+
+# Ignore missing docstrings in tests
+[tool.ruff.lint.per-file-ignores]
+"tests/*" = [
+    "D100",
+    "D101",
+    "D103",
+    "D104",
+]
+
+[tool.ruff.lint.pydocstyle]
+convention = "numpy"
+
+[tool.bumpversion]
+current_version = "1.2.1"
+parse = "(?P<major>\\d+)\\.(?P<minor>\\d+)\\.(?P<patch>\\d+)"
+serialize = ["{major}.{minor}.{patch}"]
+search = "{current_version}"
+replace = "{new_version}"
+regex = true
+ignore_missing_version = false
+ignore_missing_files = false
+tag = true
+sign_tags = false
+tag_name = "v{new_version}"
+tag_message = "Bump version: {current_version} → {new_version}"
+allow_dirty = false
+commit = true
+message = "Bump version: {current_version} → {new_version}"
+commit_args = ""
+setup_hooks = []
+pre_commit_hooks = []
+post_commit_hooks = []
+
+[[tool.bumpversion.files]]
+filename = "pyproject.toml"
+search = '\nversion = "{current_version}"'
+replace = '\nversion = "{new_version}"'
+
+[[tool.bumpversion.files]]
+filename = "sofar/__init__.py"
+search = "__version__ = '{current_version}'"
+replace = "__version__ = '{new_version}'"

sofar-1.2.1/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

{sofar-1.2.0 → sofar-1.2.1}/sofar/__init__.py

@@ -1,7 +1,8 @@
+"""Main init that determines how the sofar package is structured."""
 # -*- coding: utf-8 -*-
 __author__ = """The pyfar developers"""
 __email__ = 'info@pyfar.org'
-__version__ = '1.2.0'
+__version__ = '1.2.1'
 
 from .sofa import Sofa
 

{sofar-1.2.0 → sofar-1.2.1}/sofar/io.py

@@ -1,3 +1,4 @@
+"""Module for reading and writing Sofa files with sofar."""
 import contextlib
 import os
 import numpy as np
@@ -41,7 +42,6 @@ def read_sofa(filename, verify='auto', verbose=True):
 
     Notes
     -----
-
     1. Missing dimensions are appended when writing the SOFA object to disk.
        E.g., if ``sofa.Data_IR`` is of shape (1, 2) it is written as an array
        of shape (1, 2, 1) because the SOFA standard AES69 defines it as a
@@ -92,7 +92,6 @@ def read_sofa_as_netcdf(filename):
 
     Notes
     -----
-
     1. Missing dimensions are appended when writing the SOFA object to disk.
        E.g., if ``sofa.Data_IR`` is of shape (1, 2) it is written as an array
        of shape (1, 2, 1) because the SOFA standard AES69 defines it as a
@@ -129,8 +128,8 @@ def _read_netcdf(filename, verify, verbose, mode):
 
         if mode == "sofa":
             # get convention name and version
-            convention = getattr(file, "SOFAConventions")
-            version = getattr(file, "SOFAConventionsVersion")
+            convention = file.SOFAConventions
+            version = file.SOFAConventionsVersion
 
             # check if convention and version exist
             _verify_convention_and_version(version, convention)
@@ -213,11 +212,11 @@ def _read_netcdf(filename, verify, verbose, mode):
     if verify:
         try:
             sofa.verify(mode="read")
-        except: # noqa (No error handling - just improved verbosity)
+        except:  # noqa: E722
             raise ValueError((
                 "The SOFA object could not be verified, maybe due to erroneous"
                 " data. Call sofa=sofar.read_sofa(filename, verify=False) and "
-                "then sofa.verify() to get more information"))
+                "then sofa.verify() to get more information")) from None
 
     return sofa
 
@@ -240,7 +239,6 @@ def write_sofa(filename: str, sofa: sf.Sofa, compression=4):
 
     Notes
     -----
-
     1. Missing dimensions are appended when writing the SOFA object to disk.
        E.g., if ``sofa.Data_IR`` is of shape (1, 2) it is written as an array
        of shape (1, 2, 1) because the SOFA standard AES69 defines it as a
@@ -281,7 +279,7 @@ def _write_sofa(filename: str, sofa: sf.Sofa, compression=4, verify=True):
                     "Writing SOFA object with outdated Convention "
                     f"version {current}. It is recommend to upgrade "
                     " data with Sofa.upgrade_convention() before "
-                    "writing to disk if possible."))
+                    "writing to disk if possible."), stacklevel=2)
 
     # setting the netCDF compression parameter
     use_zlib = compression != 0
@@ -309,12 +307,10 @@ def _write_sofa(filename: str, sofa: sf.Sofa, compression=4, verify=True):
         for key in all_keys:
 
             # skip attributes
-            # Note: This definition of attribute is blurry:
-            # lax definition:
-            #   sofa._convention[key]["type"] == "attribute":
-            # strict definition:
-            #   ("_" in key and not key.startswith("Data_")) or \
-            #       key.count("_") > 1
+            # Note: The used definition of attributes is lax. The strict
+            # definition would parse `key` and assume an attribute if
+            # 1. "_" is in key and key does not start with "DATA_", or
+            # 2. key contains more than one "_"
             #
             # The strict definition is implicitly included in the SOFA standard
             # since underscores only occur for variables starting with Data_
@@ -327,7 +323,7 @@ def _write_sofa(filename: str, sofa: sf.Sofa, compression=4, verify=True):
                 sofa._dimensions[key], sofa._api["S"])
 
             # create variable and write data
-            shape = tuple(list(sofa._dimensions[key]))
+            shape = list(sofa._dimensions[key])
             tmp_var = file.createVariable(
                 key.replace("Data_", "Data."), dtype, shape,
                 zlib=use_zlib, complevel=compression)
@@ -391,7 +387,7 @@ def _format_value_for_netcdf(value, key, dtype, dimensions, S):
 
 def _format_value_from_netcdf(value, key):
     """
-    Format value from NETCDF4 file for saving in a SOFA object
+    Format value from NETCDF4 file for saving in a SOFA object.
 
     Parameters
     ----------
@@ -408,7 +404,7 @@ def _format_value_from_netcdf(value, key):
 
     if "float" in str(value.dtype) or "int" in str(value.dtype):
         if np.ma.is_masked(value):
-            warnings.warn(f"Entry {key} contains missing data")
+            warnings.warn(f"Entry {key} contains missing data", stacklevel=3)
         else:
             # Convert to numpy array or scalar
             value = np.asarray(value)