Skip to content

Commit f9fad1b

Browse files
apdavisonapdavison
committed
Improved developer documentation; add codemeta.json
1 parent c91064c commit f9fad1b

14 files changed

Lines changed: 582 additions & 17 deletions

‎.github/workflows/test.yml‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -46,6 +46,10 @@ jobs:
4646
- name: Run tests
4747
run: |
4848
pytest --cov=lazyarray -v
49+
- name: Build documentation
50+
run: |
51+
pip install sphinx
52+
cd doc && make html SPHINXOPTS="-W --keep-going"
4953
- name: Upload coverage data
5054
run: |
5155
coveralls --service=github

‎AUTHORS‎

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,14 @@
1+
The following people have contributed to lazyarray. Their affiliations at the
2+
time of the contributions are shown below.
3+
4+
* Andrew P. Davison [1]
5+
* Joël Chavas [1]
6+
* Elodie Legouée [1]
7+
* Ankur Sinha [2]
8+
9+
10+
1. Centre National de la Recherche Scientifique (CNRS), France
11+
2. University College London, UK
12+
13+
14+
Current maintainer: Andrew P. Davison <andrew.davison@cnrs.fr>

‎CODE_OF_CONDUCT.md‎

Lines changed: 46 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,46 @@
1+
# Contributor Covenant Code of Conduct
2+
3+
## Our Pledge
4+
5+
In the interest of fostering an open and welcoming environment, we as contributors and maintainers pledge to making participation in our project and our community a harassment-free experience for everyone, regardless of age, body size, disability, ethnicity, gender identity and expression, level of experience, nationality, personal appearance, race, religion, or sexual identity and orientation.
6+
7+
## Our Standards
8+
9+
Examples of behavior that contributes to creating a positive environment include:
10+
11+
* Using welcoming and inclusive language
12+
* Being respectful of differing viewpoints and experiences
13+
* Gracefully accepting constructive criticism
14+
* Focusing on what is best for the community
15+
* Showing empathy towards other community members
16+
17+
Examples of unacceptable behavior by participants include:
18+
19+
* The use of sexualized language or imagery and unwelcome sexual attention or advances
20+
* Trolling, insulting/derogatory comments, and personal or political attacks
21+
* Public or private harassment
22+
* Publishing others' private information, such as a physical or electronic address, without explicit permission
23+
* Other conduct which could reasonably be considered inappropriate in a professional setting
24+
25+
## Our Responsibilities
26+
27+
Project maintainers are responsible for clarifying the standards of acceptable behavior and are expected to take appropriate and fair corrective action in response to any instances of unacceptable behavior.
28+
29+
Project maintainers have the right and responsibility to remove, edit, or reject comments, commits, code, wiki edits, issues, and other contributions that are not aligned to this Code of Conduct, or to ban temporarily or permanently any contributor for other behaviors that they deem inappropriate, threatening, offensive, or harmful.
30+
31+
## Scope
32+
33+
This Code of Conduct applies both within project spaces and in public spaces when an individual is representing the project or its community. Examples of representing a project or community include using an official project e-mail address, posting via an official social media account, or acting as an appointed representative at an online or offline event. Representation of a project may be further defined and clarified by project maintainers.
34+
35+
## Enforcement
36+
37+
Instances of abusive, harassing, or otherwise unacceptable behavior may be reported by contacting the project team at andrew.davison@cnrs.fr. The project team will review and investigate all complaints, and will respond in a way that it deems appropriate to the circumstances. The project team is obligated to maintain confidentiality with regard to the reporter of an incident. Further details of specific enforcement policies may be posted separately.
38+
39+
Project maintainers who do not follow or enforce the Code of Conduct in good faith may face temporary or permanent repercussions as determined by other members of the project's leadership.
40+
41+
## Attribution
42+
43+
This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 1.4, available at [http://contributor-covenant.org/version/1/4][version]
44+
45+
[homepage]: http://contributor-covenant.org
46+
[version]: http://contributor-covenant.org/version/1/4/

‎CONTRIBUTING.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
See https://lazyarray.readthedocs.io/en/latest/developers/contributing.html

‎README.rst‎

Lines changed: 29 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -28,3 +28,32 @@ and memory in cases where:
2828

2929
.. image:: https://coveralls.io/repos/github/NeuralEnsemble/lazyarray/badge.svg?branch=master
3030
:target: https://coveralls.io/github/NeuralEnsemble/lazyarray?branch=master
31+
32+
33+
Documentation
34+
=============
35+
36+
Full documentation is available at https://lazyarray.readthedocs.io,
37+
including a tutorial, API reference, and a developers' guide.
38+
39+
40+
Communication
41+
=============
42+
43+
* General questions and discussion: the
44+
`NeuralEnsemble Google Group <http://groups.google.com/group/neuralensemble>`_.
45+
* Bug reports and feature requests: the
46+
`GitHub issue tracker <https://github.com/NeuralEnsemble/lazyarray/issues>`_.
47+
48+
Contributions are welcome — see the ``CONTRIBUTING.md`` file at the root
49+
of the repository and the
50+
`developers' guide <https://lazyarray.readthedocs.io/en/latest/developers.html>`_
51+
for details. All contributors are expected to follow the
52+
`Code of Conduct <https://github.com/NeuralEnsemble/lazyarray/blob/master/CODE_OF_CONDUCT.md>`_.
53+
54+
55+
License
56+
=======
57+
58+
lazyarray is released under the BSD-3-Clause license; see the ``LICENSE``
59+
file for the full text.

‎codemeta.json‎

Lines changed: 76 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,76 @@
1+
{
2+
"@context": "https://w3id.org/codemeta/3.0",
3+
"@type": "SoftwareSourceCode",
4+
"name": "lazyarray",
5+
"description": "lazyarray is a Python package that provides a lazily-evaluated numerical array class, ``larray``, based on and compatible with NumPy arrays.\n\nLazy evaluation means that any operations on the array (potentially including array construction) are not performed immediately, but are delayed until evaluation is specifically requested. Evaluation of only parts of the array is also possible.\n\nUse of an ``larray`` can potentially save considerable computation time and memory in cases where:\n\n* arrays are used conditionally (i.e. there are cases in which the array is never used)\n* only parts of an array are used (for example in distributed computation, in which each MPI node operates on a subset of the elements of the array)",
6+
"author": [
7+
{
8+
"givenName": "Andrew P.",
9+
"familyName": "Davison",
10+
"type": "Person",
11+
"id": "http://orcid.org/0000-0002-4793-7541"
12+
},
13+
{
14+
"givenName": "Joël",
15+
"familyName": "Chavas",
16+
"type": "Person"
17+
},
18+
{
19+
"givenName": "Elodie",
20+
"familyName": "Legouée",
21+
"type": "Person"
22+
},
23+
{
24+
"givenName": "Ankur",
25+
"familyName": "Sinha",
26+
"type": "Person"
27+
}
28+
],
29+
"license": [
30+
"https://spdx.org/licenses/BSD-3-Clause"
31+
],
32+
"version": "0.7.0",
33+
"dateModified": "2026-01-21",
34+
"codeRepository": "https://github.com/NeuralEnsemble/lazyarray/",
35+
"downloadUrl": "https://files.pythonhosted.org/packages/30/2c/fe1319b150a6800d9c1336d633590bf170573795fc7ecf3cb39f7707e62d/lazyarray-0.7.0.tar.gz",
36+
"relatedLink": [
37+
"https://lazyarray.readthedocs.io/"
38+
],
39+
"softwareHelp": [
40+
"https://github.com/NeuralEnsemble/lazyarray/issues"
41+
],
42+
"releaseNotes": "* Minor updates to work with recent versions of NumPy and SciPy\n* Add support for Python 3.13, 3.14; remove testing for Python 3.9 and below, and for NumPy 1.22 and below.",
43+
"programmingLanguage": [
44+
"Python"
45+
],
46+
"operatingSystem": [
47+
"Windows",
48+
"Linux",
49+
"macOS"
50+
],
51+
"availableOnDevice": [
52+
"high-performance computer",
53+
"desktop"
54+
],
55+
"softwareRequirements": [
56+
"NumPy>=1.23.5"
57+
],
58+
"softwareSuggestions": [
59+
"SciPy>=1.9.3"
60+
],
61+
"developmentStatus": "active",
62+
"continuousIntegration": "https://github.com/NeuralEnsemble/lazyarray/actions",
63+
"issueTracker": "https://github.com/NeuralEnsemble/lazyarray/issues",
64+
"keywords": [
65+
"lazy evaluation",
66+
"array"
67+
],
68+
"maintainer": [
69+
{
70+
"givenName": "Andrew P.",
71+
"familyName": "Davison",
72+
"type": "Person",
73+
"id": "http://orcid.org/0000-0002-4793-7541"
74+
}
75+
]
76+
}

‎doc/conf.py‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -123,7 +123,7 @@
123123
# Add any paths that contain custom static files (such as style sheets) here,
124124
# relative to this directory. They are copied after the builtin static files,
125125
# so a file named "default.css" will overwrite the builtin "default.css".
126-
html_static_path = ['_static']
126+
html_static_path = []
127127

128128
# If not '', a 'Last updated on:' timestamp is inserted at every page bottom,
129129
# using the given strftime format.

‎doc/developers.txt‎

Lines changed: 24 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -2,27 +2,35 @@
22
Developers' guide
33
=================
44

5-
TO BE COMPLETED
5+
This guide contains information about contributing to lazyarray development,
6+
about the internal architecture of the package, and about the maintenance and
7+
release workflow.
68

7-
Testing
8-
=======
9+
lazyarray is open-source software (BSD-3-Clause) with a community-based
10+
development model: contributions are welcomed, and the direction of the
11+
project is determined by the needs of its users — most prominently
12+
`PyNN <http://neuralensemble.org/PyNN/>`_, but also any other downstream
13+
project that needs lazily-evaluated NumPy-compatible arrays.
914

10-
In the `test` sub-directory, run::
15+
There are several ways to contribute:
1116

12-
$ pytest
17+
* reporting bugs, errors and other mistakes in the code or documentation;
18+
* making suggestions for improvements;
19+
* fixing bugs;
20+
* extending the supported set of NumPy operations;
21+
* helping to maintain the package across new versions of Python, NumPy and
22+
SciPy.
1323

14-
To see how well the tests cover the code base, run::
24+
The following sections contain guidelines for each of these.
1525

16-
$ pytest --cov=lazyarray --cov-report html --cov-report term-missing
26+
.. toctree::
27+
:maxdepth: 2
1728

29+
developers/bug_reports
30+
developers/contributing
31+
developers/architecture
32+
developers/governance
33+
developers/roadmap
1834

19-
Making a release
20-
================
2135

22-
* Update the version numbers in pyproject.toml, lazyarray.py, doc/conf.py and doc/installation.txt
23-
* Update changelog.txt
24-
* Run all the tests with Python 3
25-
* python -m build
26-
* twine upload dist/lazyarray-<version>*
27-
* Commit the changes, tag with release number, push to Github
28-
* Rebuild the documentation at http://lazyarray.readthedocs.org/
36+
.. _`NeuralEnsemble Google Group`: http://groups.google.com/group/neuralensemble

‎doc/developers/architecture.txt‎

Lines changed: 71 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,71 @@
1+
============
2+
Architecture
3+
============
4+
5+
lazyarray is a single-module package: all the code lives in
6+
``lazyarray.py`` (around 600 lines), and the test suite lives in the
7+
``test/`` directory. The Sphinx documentation source is in ``doc/``.
8+
9+
The public surface is the :class:`larray` class together with the
10+
``partial_shape`` helper. Everything else in ``lazyarray.py`` is internal.
11+
12+
The core data structure
13+
=======================
14+
15+
An :class:`larray` instance stores three pieces of state:
16+
17+
* ``base_value`` — the underlying source of element values. This may be a
18+
number, a NumPy array, a SciPy sparse matrix, a sequence, an iterator,
19+
a generator, or a callable of the form ``f(i)`` or ``f(i, j)``.
20+
* ``operations`` — an ordered list of ``(callable, operand)`` pairs that
21+
describes the queue of arithmetic operations to apply to the base value.
22+
* ``_shape`` and ``_dtype`` — metadata used to validate broadcasting and
23+
to short-circuit element-wise evaluation.
24+
25+
Arithmetic on an :class:`larray` does not change the base value. Instead,
26+
each operator (``__add__``, ``__mul__``, etc.) is built by the
27+
``lazy_operation`` factory and appends an entry to ``operations`` on a
28+
deep-copy of the array. The actual computation is deferred.
29+
30+
Evaluation
31+
==========
32+
33+
Element values are computed only when the array is indexed or its
34+
``evaluate()`` method is called. The flow is:
35+
36+
1. The address (a slice, integer, tuple, or boolean mask) is normalised
37+
via ``full_address`` and the resulting sub-array shape is derived
38+
via ``partial_shape``.
39+
2. The relevant subset of the base value is materialised — by calling
40+
the function on the requested indices, advancing the iterator,
41+
slicing the array, or returning the scalar.
42+
3. The queued operations are applied in order to that subset.
43+
44+
This means that, even for very large logical arrays, only the elements
45+
that are actually requested are ever computed. This is the property that
46+
makes lazyarray useful in MPI-parallel simulations, where each process
47+
typically needs only a slice of a large parameter array.
48+
49+
Decorators
50+
==========
51+
52+
A handful of small decorators capture cross-cutting concerns:
53+
54+
* ``check_shape`` ensures that an operand has a shape compatible with
55+
the array;
56+
* ``requires_shape`` raises if the array's shape is not yet defined;
57+
* ``lazy_operation`` / ``lazy_inplace_operation`` / ``lazy_unary_operation``
58+
generate the magic methods used for arithmetic.
59+
60+
Extension points
61+
================
62+
63+
Two extension points are provided for users who need to plug in their own
64+
value types:
65+
66+
* a base value object that implements a method ``lazily_evaluate`` will
67+
have that method called during evaluation (used, for example, to
68+
integrate Brian quantities);
69+
* an object that is ``Sized`` but should nonetheless be treated as a
70+
single element can declare this by setting an attribute
71+
``is_lazyarray_scalar = True``.

‎doc/developers/bug_reports.txt‎

Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,22 @@
1+
================================
2+
Bug reports and feature requests
3+
================================
4+
5+
If you find a bug or would like to suggest a new feature for lazyarray,
6+
please go to https://github.com/NeuralEnsemble/lazyarray/issues. First
7+
check that there is not already an existing ticket for your bug or request,
8+
then click on "New issue" to create a new one (you will need a GitHub
9+
account, but creating one is simple and free).
10+
11+
When reporting a bug, please include:
12+
13+
* the version of lazyarray, NumPy (and SciPy, if applicable), and Python
14+
you are using;
15+
* the operating system;
16+
* a minimal reproducer — the shortest possible code snippet that exhibits
17+
the problem;
18+
* the full traceback or unexpected output.
19+
20+
For general questions about how to use lazyarray, the
21+
`NeuralEnsemble Google Group <http://groups.google.com/group/neuralensemble>`_
22+
is a better venue than the issue tracker.

0 commit comments

Comments
 (0)