Merge pull request #189 from NeuralEnsemble/experimental

feat!: regenerate for 2.3.1

.github/workflows/ci.yml

@@ -39,7 +39,7 @@ jobs:
       if: ${{ matrix.runs-on == 'macos-latest' }}
       run: |
         brew install hdf5
-        
+
     - name: Build package
       run: |
         pip install .[full]

.pre-commit-config.yaml

@@ -0,0 +1,15 @@
+# See https://pre-commit.com for more information
+# See https://pre-commit.com/hooks.html for more hooks
+repos:
+-   repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v4.4.0
+    hooks:
+    -   id: trailing-whitespace
+    -   id: end-of-file-fixer
+    -   id: check-added-large-files
+- repo: https://github.com/astral-sh/ruff-pre-commit
+  rev: v0.4.1
+  hooks:
+    - id: ruff
+      args: [ "--select", "I", "--fix" ]
+    - id: ruff-format

CONTRIBUTING.md

@@ -0,0 +1,112 @@
+# Contributing
+
+Please open issues to discuss enhancements and bugs that you may encounter with
+libNeuroML. Pull requests with enhancements and bug fixes are welcome.
+
+## Virtual environments and editable installs
+
+It is best to use [virtual environments](https://docs.python.org/3/tutorial/venv.html) when developing Python packages.
+This ensures that one uses a clean environment that includes the necessary
+dependencies and does not affect the overall system installation.
+
+For quick development, consider using [editable installs](https://setuptools.pypa.io/en/latest/userguide/development_mode.html).
+The dependencies are broken down in the `setup.cfg` file. To get a complete development environment, one can run:
+
+
+    pip install -e .[dev]   # an editable install with all development dependecies installed
+
+
+## Code style
+
+1. The source code uses spaces, and each tab is equivalent to 4 spaces.
+
+2. We use the [reStructuredText (reST)
+   format](https://stackoverflow.com/a/24385103/375067) for Python docstrings.
+   Please document your code when opening pull requests.
+   All methods/functions/modules *must* include docstrings that explain the parameters.
+
+3. We use [ruff](https://pypi.org/project/ruff/) to format and lint our code. (See the section on pre-commit below.)
+
+4. Please use [type hints](https://docs.python.org/3/library/typing.html) wherever applicable.
+   You can set up type checkers such as [mypy](https://mypy.readthedocs.io/) to use type hints in your development environment/IDE.
+
+
+        pip install mypy
+
+
+### Pre-commit
+
+A number of [pre-commit](https://pre-commit.com/) hooks are used to improve code-quality.
+Please run the following code to set up the pre-commit hooks:
+
+    $ pre-commit install
+
+The hooks will be run at each `git commit`.
+Please see `.pre-commit-config.yaml` for information on what hooks we run.
+
+
+### Commit messages
+
+Writing good commit messages makes things easy to follow.
+Please see these posts:
+
+- [How to write a Git commit message](https://cbea.ms/git-commit/)
+- While not compulsory, we prefer [conventional commits](https://www.conventionalcommits.org/en/v1.0.0/)
+
+
+## Tests
+
+Bug fixes and new features should include unit tests to test for correctness.
+One can base new tests off the current ones included in the `tests/` directory.
+To see how tests are run, please see the [GitHub Actions configuration file](https://github.com/NeuralEnsemble/libNeuroML/blob/development/.github/workflows/ci.yml).
+
+We use [pytest](https://docs.pytest.org/) for unit testing.
+One can run it from the root of the repository:
+
+    pytest
+
+
+To run specific tests, one can use the `-k` flag:
+
+
+    pytest -k "..."
+
+
+## Pull Request Process
+
+1. Please contribute pull requests against the `development` branch.
+2. Please ensure that the automated build for your pull request passes.
+3. Please write good commit messages (see the section above).
+
+### Updating your pull request branch
+
+Over time, as pull requests are reviewed, the `development` branch continues to move on with other changes.
+Sometimes, it can be useful/necessary to pull in these changes to the pull request branch, using the following steps.
+
+Add the upstream libNeuroML repository as a remote:
+
+
+    git remote add upstream https://github.com/NeuralEnsemble/libNeuroML.git
+
+
+Update your local copy of the `development` branch, and the remote copy in your fork:
+
+
+    git checkout development
+    git pull upstream development
+    git push
+
+
+Pull in changes from development to your branch:
+
+
+    git checkout <feature branch being used for PR>
+    git merge development
+
+
+If there are merge conflicts, you will need to [resolve these](https://git-scm.com/book/en/v2/Git-Branching-Basic-Branching-and-Merging#_basic_merge_conflicts), since merging the feature branch in the pull request will also result in these.
+After any merge conflicts have been resolved (or if there aren't any), you can
+push your branch to your fork to update the pull request:
+
+
+    git push

doc/conf.py

@@ -11,8 +11,8 @@
 # All configuration values have a default; values that are commented out
 # serve to show the default.
 
-import sys
 import os
+import sys
 
 # If extensions (or modules to document with autodoc) are in another directory,
 # add these directories to sys.path here. If the directory is relative to the

doc/devdocs/index.rst

@@ -9,4 +9,3 @@ Contributing
    implementation_of_bindings
    meeting_june_2012
    nodes_segments_sections
-

doc/devdocs/meeting_june_2012.rst

@@ -109,7 +109,7 @@ Mike V was asked to add a clone method to a morphology.
 It was decided that fraction_along should be a property of segment.
 
 The syntax for segment groups should be as follows:
-group=morph.segment_groups['axon_group'] 
+group=morph.segment_groups['axon_group']
 (in connect merge groups should be false by default - throw an exception, tell the user setting merge_groups = True or rename group will fix this)
 
 This was a subject of great debate and has not been completely settled.

doc/devdocs/nodes_segments_sections.rst

@@ -58,7 +58,7 @@ unbranched segmentGroups, which can be used as the basis for sections in any par
 in them, or be ignored by any other application.
 
 In libNeuroML, a section-like concept can be added at API level, to facilitate building cells, to facilitate import/export
-to/from simulators supporting this concept, and to serve as a basis for recompartmentalisation of cells. 
+to/from simulators supporting this concept, and to serve as a basis for recompartmentalisation of cells.
 
 
 
@@ -96,7 +96,7 @@ to the **parent** element, i.e.
     <parent segment="2" fractionAlong="0.5"/>
 
 This is not possible in a node based format, but represents a logically consistent description of what the modeller
-wants. 
+wants.
 
 
 What to do?
@@ -108,4 +108,4 @@ enforce "best practice"?
 PG: I'd argue for the first approach, as it retains as much as possible of what the original reconstructor/simulator specified.
 An API which enforces a policy when it encounters a non optimal morphology (e.g. moving all dendrites to connection points,
 inserting new nodes) will alter the original data in perhaps unintended ways, and that information will be lost by subsequent readers.
-It should be up to each parsing application to decide what to do with the extra information when it reads in a file.
+It should be up to each parsing application to decide what to do with the extra information when it reads in a file.

doc/helpers/nml-core-docs.py

@@ -7,7 +7,6 @@
 Copyright 2023 NeuroML authors
 """
 
-
 import textwrap
 
 print("Generating list of nml classes")

doc/refs.bib

@@ -20,4 +20,3 @@ @Article{Vella2014
   timestamp    = {2019-02-20},
   year         = {2014},
 }
-

doc/userdocs/api.rst

@@ -12,5 +12,3 @@ You can find information on these in the pages below.
    writers
    utils
    arraymorph
-
-

doc/userdocs/arraymorph.rst

@@ -6,5 +6,3 @@
     :members:
     :undoc-members:
     :show-inheritance:
-
-

doc/userdocs/coreclasses_list.txt

@@ -2216,5 +2216,3 @@ basePyNNIaFCondCell
    :undoc-members:
    :show-inheritance:
    :inherited-members:
-
-

doc/userdocs/examples.rst

@@ -2,7 +2,7 @@
 Examples
 ========
 
-The examples in this section are intended to give in depth overviews of how to accomplish 
+The examples in this section are intended to give in depth overviews of how to accomplish
 specific tasks with libNeuroML.
 
 These examples are located in the neuroml/examples directory and can
@@ -19,7 +19,7 @@ Loading and modifying a file
 ----------------------------
 
 .. literalinclude:: ../../neuroml/examples/loading_modifying_writing.py
- 
+
 
 Building a network
 ------------------
@@ -30,7 +30,7 @@ Building a 3D network
 ---------------------
 
 .. literalinclude:: ../../neuroml/examples/build_3D_network.py
- 
+
 Ion channels
 ------------
 

doc/userdocs/index.rst

@@ -9,4 +9,3 @@ User guide
    api
    examples
    bibliography
-

doc/userdocs/install.rst

@@ -97,7 +97,7 @@ If all tests passed correctly, your output should look something like this:
     .......
     ----------------------------------------------------------------------
     Ran 55 tests in 40.1s
-    
+
     OK
 
 You can also use PyTest to run tests.

doc/userdocs/loaders.rst

@@ -5,5 +5,3 @@
     :members:
     :undoc-members:
     :show-inheritance:
-
-

doc/userdocs/writers.rst

@@ -5,4 +5,3 @@
     :members:
     :undoc-members:
     :show-inheritance:
-

neuroml/__init__.py

@@ -1,7 +1,18 @@
-from .nml.nml import *  # allows importation of all neuroml classes
+import logging
+
+from . import build_time_validation
 from .__version__ import __version__ as __version__
 from .__version__ import __version_info__ as __version__info__
 from .__version__ import current_neuroml_version as current_neuroml_version
+from .nml.nml import *  # allows importation of all neuroml classes
+
+logging.basicConfig(
+    format="libNeuroML >>> %(levelname)s - %(message)s",
+    level=logging.WARN,
+)
+
+logger = logging.getLogger(__name__)
+logger.setLevel(logging.INFO)
 
 
 def print_(text, verbose=True):
@@ -10,3 +21,45 @@ def print_(text, verbose=True):
         # if not isinstance(text, str): text = text.decode('ascii')
         if verbose:
             print("%s%s" % (prefix, text.replace("\n", "\n" + prefix)))
+
+
+def disable_build_time_validation():
+    """Disable build time validation.
+
+    This will disable the validation of components when they are being created
+    using the factory functions, such as component_factory, and add.
+
+    This is useful for certain cases where a new component cannot necessarily
+    be created in a valid state from the beginning. For example, a population
+    is usually created after a network, but a network without a population
+    would not be valid.
+
+    This switch provides a convenient way to disable this check.
+
+    Please note that this should only be used sparingly, and not abused to turn
+    off build time validation completely.
+
+    .. versionadded:: 0.6.0
+    """
+    build_time_validation.ENABLED = False
+    logger.warning("Build time validation has been disabled.")
+
+
+def enable_build_time_validation():
+    """Enable build time validation
+
+    .. versionadded:: 0.6.0
+    """
+    build_time_validation.ENABLED = True
+    logger.info("Build time validation has been enabled.")
+
+
+def get_build_time_validation() -> bool:
+    """Get build time validation
+
+    .. versionadded:: 0.6.0
+
+    :returns: state of build time validation
+    :rtype: bool
+    """
+    return build_time_validation.ENABLED

neuroml/__version__.py

@@ -6,7 +6,6 @@
 Copyright 2023 NeuroML contributors
 """
 
-
 try:
     import importlib.metadata
 
@@ -19,4 +18,4 @@
 __version_info__: tuple = tuple(int(i) for i in __version__.split("."))
 
 
-current_neuroml_version: str = "v2.3"
+current_neuroml_version: str = "v2.3.1"

neuroml/arraymorph.py

@@ -3,6 +3,7 @@
 """
 
 import numpy as np
+
 import neuroml
 
 

neuroml/arraymorph_load_time_benchmark.py

@@ -1,4 +1,5 @@
 import numpy as np
+
 import neuroml
 import neuroml.arraymorph as am
 

neuroml/benchmarks/arraymorph_benchmarks.py

@@ -1,15 +1,19 @@
 """
 Benchmarks for reading and writing arraymorphs.
 """
+
 from __future__ import print_function
+
+import os
+import tempfile
+import time
+
 import numpy as np
-from neuroml import arraymorph as am
+from matplotlib import pyplot as plt
+
 import neuroml
 import neuroml.writers
-import tempfile
-from matplotlib import pyplot as plt
-import time
-import os
+from neuroml import arraymorph as am
 
 
 def timeit(method):