Update documentation #9

asmeurer · 2024-01-24T00:43:01Z

No description provided.

asmeurer · 2024-01-24T00:56:36Z

@rgommers if you have a chance, can you review this?

In addition to the changes in this PR, can you also take a look at the repo as a whole. I think I have everything ready to do an initial release, but I don't know if I forgot anything.

I also opened some issues on this repo for ideas of things we can do in the future. But I want to keep the first release as close to the current numpy.array_api as possible.

rgommers

This looks quite good Aaron, I only have a few minor comments.

rgommers · 2024-01-24T19:17:12Z

CHANGELOG.md

@@ -0,0 +1,30 @@
+# array-api-strict Changelog
+
+## 1.0 (????)


rgommers · 2024-01-24T19:18:08Z

CHANGELOG.md

+extracted from the git history of numpy/array_api/ (see the [README](README.md)).
+
+Additionally, the following changes are new to `array_api_strict` from
+`numpy.array_api` in NumPy 1.26 (the last major NumPy release to include


Suggested change

`numpy.array_api` in NumPy 1.26 (the last major NumPy release to include

`numpy.array_api` in NumPy 1.26 (the last NumPy feature release to include

rgommers · 2024-01-24T19:21:16Z

README.md

+  standard are included. All signatures in array-api-strict use
+  [positional-only
+  arguments](https://data-apis.org/array-api/latest/API_specification/function_and_method_signatures.html#function-and-method-signatures).
+  As noted above, only array_api_strict array objects are accepted by


formatting: array_api_strict needs backticks

rgommers · 2024-01-24T19:22:03Z

README.md

+  arguments](https://data-apis.org/array-api/latest/API_specification/function_and_method_signatures.html#function-and-method-signatures).
+  As noted above, only array_api_strict array objects are accepted by
+  functions, except in the places where the standard allows Python scalars
+  (i.e., functions to not automatically call `asarray` on their inputs).


this sentence reads slightly awkward to me. maybe it's a typo (to not -> do not)?

rgommers · 2024-01-24T19:22:49Z

README.md

+
+- The
+  [indexing](https://data-apis.org/array-api/latest/API_specification/indexing.html)
+  semantics required by the standard are not


incomplete sentence here

rgommers · 2024-01-24T19:23:22Z

README.md

+
+- The array object type itself is private and should not be accessed.
+  Subclassing or otherwise trying to directly initialize this object is not
+  supported. Arrays should created with one of the [array creation


typo: "should be created"

rgommers · 2024-01-24T19:24:11Z

README.md

+
+## Caveats
+
+array-api-strict is a thin pure Python wrapper around NumPy. NumPy 2.0 fully


I suggest: "NumPy 2.0 has nearly full support for ....", since there are a few aspects that don't comply (e.g., returning scalars)

I'll change this, but I was under the impression that scalars were not actually breaking compliance. As long as scalars duck-type as 0-D arrays, which they do, then it's just an implementation detail that numpy has a separate type for them.

maybe, not sure if the duck-typing really is 100%. there's a few other reasons though, see the "not adopted part in the PR for NEP 56

Where is NEP 56? Google comes up with nothing.

numpy/numpy#25542

I'm going to continue this discussion over there since this is closed, but that NEP seems to just state that scalars aren't in compliance without actually explaining why. numpy/numpy#25542 (comment)

rgommers · 2024-01-24T19:26:04Z

array_api_strict/__init__.py

- Complex number support in array API spec is planned but not yet finalized,
-  as are the fft extension and certain linear algebra functions such as eig
-  that require complex dtypes.
+array_api_strict is a strict, minimal implementation of the Python array


need backticks here as well

array_api_strict/__init__.py

rgommers · 2024-01-24T19:38:49Z

In addition to the changes in this PR, can you also take a look at the repo as a whole. I think I have everything ready to do an initial release, but I don't know if I forgot anything.

I think it can be shipped as is, however you may want to do some of the following (can be done later):

Packaging: we may want to be good citizens and use pyproject.toml here, and get rid of all setup.* content
versioneer is pretty awful, and this package is really simple. I'd just use 1.0 and then 1.1-dev in pyproject.toml and leave it at that, rather than use thousands of lines of questionable-quality code to support a simple version string.

I also opened some issues on this repo for ideas of things we can do in the future. But I want to keep the first release as close to the current numpy.array_api as possible.

Good ideas, +1 to both the first release plan and all of those things as follow-ups.

rgommers · 2024-01-24T19:39:00Z

I'll give this a try with SciPy

rgommers · 2024-01-24T19:56:21Z

Looks like the switchover is easy and everything works as expected for SciPy.

asmeurer · 2024-01-24T20:11:16Z

I've used versioneer on dozens of projects and never had any issues with it. All the code in versioneer is used for generating development version numbers and doing packaging. The actual resulting package has a very simple file generated in it. Here's what it creates for this branch

# This file was generated by 'versioneer.py' (0.29) from
# revision-control system data, or from the parent directory name of an
# unpacked source archive. Distribution tarballs contain a pre-generated copy
# of this file.

import json

version_json = '''
{
 "date": "2024-01-23T17:55:23-0700",
 "dirty": false,
 "error": null,
 "full-revisionid": "c2d570061e8434b58c4e6609e2a849cf75e6a390",
 "version": "0+untagged.193.gc2d5700"
}
'''  # END VERSION_JSON


def get_versions():
    return json.loads(version_json)

Admittedly, even that is more complicated than it could be. It could just generate a file with just `version = ''. But it's way simpler for runtime than, e.g., setuptools_scm, which grabs the version number from the package metadata. I don't like that at all. If you know of a simpler tool I'm open to using it, but I do like to have something that lets me write the version number just once (in the tag). Otherwise I forget to update it, like I recently did for array-api-compat (we can't use versioneer there because of the vendorability requirement). I don't actually care as much about the git hash version thing, although it is nice to have and it occasionally helps with debugging user issues.

rgommers · 2024-01-24T20:21:26Z

If you know of a simpler tool I'm open to using it, but I do like to have something that lets me write the version number just once (in the tag).

Imho none of these tools are worth it, for a one-line change per release. versioneer specifically we've had problems with in NumPy, and since dropped - as did Matplotlib and others. If you've had to debug versioneer code just once, you notice it's 2000+ lines of bad code generating 500+ lines more code to then ship.

But okay, I don't have to make the updates here, so your call.

asmeurer · 2024-01-24T20:25:44Z

OK, I'm going to try to do a release. Based on my experience with array-api-compat, getting the auto-deploy to work the first time around can be a little annoying, so I may end up pushing a 1.0 tag to this repo multiple times.

asmeurer · 2024-01-24T20:45:37Z

OK, array-api-strict 1.0 has been released. Now I need to create a conda-forge package.

rgommers · 2024-01-24T21:30:32Z

Great, thanks!

asmeurer added 5 commits January 23, 2024 17:39

Update the README

2e12b65

Update the module docstring

07d482f

Fixes in the README

e4d0798

Add a CHANGELOG

2bc5edd

Merge branch 'main' into docs-update

c2d5700

rgommers approved these changes Jan 24, 2024

View reviewed changes

asmeurer added 2 commits January 24, 2024 13:15

Wording updates from review

c027af9

Add .DS_Store to .gitignore

c0f1534

asmeurer temporarily deployed to publish-package January 24, 2024 20:43 — with GitHub Actions Inactive

asmeurer merged commit 397713f into data-apis:main Jan 24, 2024
30 of 36 checks passed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Update documentation #9

Update documentation #9

asmeurer commented Jan 24, 2024

asmeurer commented Jan 24, 2024

rgommers left a comment

rgommers Jan 24, 2024

rgommers Jan 24, 2024

rgommers Jan 24, 2024

rgommers Jan 24, 2024

rgommers Jan 24, 2024

rgommers Jan 24, 2024

rgommers Jan 24, 2024

asmeurer Jan 24, 2024

rgommers Jan 24, 2024

asmeurer Jan 24, 2024

rgommers Jan 24, 2024

asmeurer Jan 24, 2024

rgommers Jan 24, 2024

rgommers commented Jan 24, 2024

rgommers commented Jan 24, 2024

rgommers commented Jan 24, 2024

asmeurer commented Jan 24, 2024

rgommers commented Jan 24, 2024

asmeurer commented Jan 24, 2024

asmeurer commented Jan 24, 2024

rgommers commented Jan 24, 2024

	`numpy.array_api` in NumPy 1.26 (the last major NumPy release to include
	`numpy.array_api` in NumPy 1.26 (the last NumPy feature release to include


		## Caveats

		array-api-strict is a thin pure Python wrapper around NumPy. NumPy 2.0 fully

Update documentation #9

Update documentation #9

Conversation

asmeurer commented Jan 24, 2024

asmeurer commented Jan 24, 2024

rgommers left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

rgommers commented Jan 24, 2024

rgommers commented Jan 24, 2024

rgommers commented Jan 24, 2024

asmeurer commented Jan 24, 2024

rgommers commented Jan 24, 2024

asmeurer commented Jan 24, 2024

asmeurer commented Jan 24, 2024

rgommers commented Jan 24, 2024