[DOC, DISPATCH] : updated and added `backend.py`'s docs #7305

Schefflera-Arboricola · 2024-02-19T13:36:37Z

https://output.circle-artifacts.com/output/job/b5389424-c908-4ad8-8fa1-fcd1ff17ec74/artifacts/0/doc/build/html/reference/utils.html#backends

…IO object at 0x7f446194c5e0>

dschult

Thanks for this! It is very helpful. I have a couple of comments below that you should change/adapt as desired.

It might be good to start with language that is aimed at explaining what this is to a user, and then be explicit about when it shifts to being language for someone who wants to set up a backend.

networkx/utils/backends.py

Schefflera-Arboricola · 2024-02-28T15:32:10Z

Thanks @dschult @eriknw and @rlratzel for the review!

aaronzo · 2024-03-04T18:27:21Z

networkx/utils/backends.py

+1.  To be a valid NetworkX backend, a package must register an entry_point
+    `networkx.backends` with a key pointing to the handler. (`how? <https://packaging.python.org/en/latest/guides/creating-and-discovering-plugins/#using-package-metadata>`_)
+
+    You can include the following entry-point in your package's `pyproject.toml` file::


This example works if a package is using setuptools, but that may not be the case - e.g. if using poetry or some other build tool, or if a package isn't using a pyproject.toml yet. I think it might be good just to note that this is an example specific to that.

Just for context, in poetry this is done using:

[tool.poetry.plugins."networkx.backends"] entry_point_name = "your_dispatcher_class"

Maybe change the wording to something like:

The way you so this depends on your distribution tools. If you use `pyproject.toml` you can add the entry-point as follows::

aaronzo · 2024-03-04T18:28:28Z

networkx/utils/backends.py

+        [project.entry-points."networkx.backends"]
+        entry_point_name = "your_dispatcher_class"


Is there any reason why 'entry_point_name' shouldn't just be the backend name?

Can we call it backend_name here? That's what we call it in the Dispatcher decorator code. So something like:
backend_name = "your_dispatcher_class".

I used entry_point_name instead of backend_name because I thought backend names have the nx- in the start and entry-points do not, but I have added a note that clarifies this. Let me know if that looks good to you. Thanks for the review!

dschult

I've put a bunch of comments below -- mostly in the top part where we are talking about what backends are and how to implement one. See what you think. Push back if you don't think it makes the wording better. :)

networkx/utils/backends.py

dschult · 2024-03-07T03:59:27Z

networkx/utils/backends.py

+Also, you might have seen the `@nx._dispatchable` decorator on many of the NetworkX
+functions. It is used on functions that can have a backend implementation.


Suggested change

Also, you might have seen the `@nx._dispatchable` decorator on many of the NetworkX

functions. It is used on functions that can have a backend implementation.

We are also working on an automatic backend system which could discover which

backend to use for different situations.

Also, if you've looked at NetworkX function source code, you might have seen the

`@nx._dispatchable` decorator on many functions. That decorator makes functions

check whether to dispatch to a backend implementation or run the NetworkX code.

dschult · 2024-03-07T04:01:28Z

networkx/utils/backends.py

+computation work to it. Currently, the following backends are supported by NetworkX:
+
+- `graphblas <https://github.com/python-graphblas/graphblas-algorithms>`_
+- `cugraph <https://github.com/rapidsai/cugraph/tree/branch-24.04/python/nx-cugraph>`_
+- `parallel <https://github.com/networkx/nx-parallel>`_
+- `loopback` is for testing purposes only and is not a real backend.


Do we want to claim this is the list of backends? Other people could have backends and we would never know about it. Perhaps we can say that these are some examples of backends.

networkx/utils/backends.py

dschult · 2024-03-07T04:36:16Z

Also, what do people think about moving the backend documentation out of the "Utillities" section and into its own section? The Utilities page is getting pretty long and it might be nice to have a page just for Backends that we could point people to.

Co-authored-by: Dan Schult <dschult@colgate.edu>

networkx/utils/backends.py

Co-authored-by: Dan Schult <dschult@colgate.edu>

dschult

I think these docs look good. And we can obviously change/improve/adapt them further as we go.

Thanks Aditi for putting this together!

eriknw · 2024-03-20T04:34:31Z

networkx/utils/backends.py

+Creating a Custom backend
+--------------------------


Did you mean to make all of the header underlines to be one character longer than the header? As far as I know, they're typically the same length in networkx docs.

yes, the convention is to use the --- of the same length as the title (ref).

rossbar

Thanks @Schefflera-Arboricola ! I pushed up a few formatting updates while being careful to leave the content itself unchanged by and large.

Co-authored-by: Dan Schult <dschult@colgate.edu> Co-authored-by: Ross Barnowski <rossbar@caltech.edu>

Schefflera-Arboricola added 6 commits February 19, 2024 19:04

updated backend.py's user-facing docs

70fc5d3

typo fix, style fix

8f932cb

style fix

7278c4b

updated backend.py docs

532a1bc

indentation fix

5a1cecb

syntax fix

fc45e04

dschult added type: Documentation Dispatching Related to dispatching and backend support labels Feb 19, 2024

Schefflera-Arboricola added 2 commits February 20, 2024 23:37

added more docs

5b40ff6

got PIL.UnidentifiedImageError: cannot identify image file <_io.Bytes…

cf53b2b

…IO object at 0x7f446194c5e0>

dschult reviewed Feb 20, 2024

View reviewed changes

networkx/utils/backends.py Show resolved Hide resolved

networkx/utils/backends.py Outdated Show resolved Hide resolved

networkx/utils/backends.py Outdated Show resolved Hide resolved

rlratzel reviewed Feb 26, 2024

View reviewed changes

networkx/utils/backends.py Outdated Show resolved Hide resolved

networkx/utils/backends.py Outdated Show resolved Hide resolved

Schefflera-Arboricola and others added 3 commits February 28, 2024 20:52

updated backend docs

808d2a8

Merge branch 'main' into backend_docs

6824bc0

style fix

bfe2836

aaronzo reviewed Mar 4, 2024

View reviewed changes

dschult reviewed Mar 7, 2024

View reviewed changes

Schefflera-Arboricola and others added 5 commits March 13, 2024 23:13

updated docs

79297b4

Update networkx/utils/backends.py

d127fba

Co-authored-by: Dan Schult <dschult@colgate.edu>

Update backends.py intro

3841a21

Co-authored-by: Dan Schult <dschult@colgate.edu>

Merge branch 'main' into backend_docs

f683017

updated docs

2cf413a

dschult reviewed Mar 15, 2024

View reviewed changes

networkx/utils/backends.py Outdated Show resolved Hide resolved

dschult and others added 2 commits March 16, 2024 07:48

Merge branch 'main' into backend_docs

57d17ee

Update networkx/utils/backends.py

ef65c15

Co-authored-by: Dan Schult <dschult@colgate.edu>

dschult approved these changes Mar 20, 2024

View reviewed changes

eriknw reviewed Mar 20, 2024

View reviewed changes

Minor rst touchups.

e03f30f

Fixup docstring formatting.

6140bb7

rossbar approved these changes Mar 21, 2024

View reviewed changes

rossbar merged commit 9ad7887 into networkx:main Mar 21, 2024
41 checks passed

jarrodmillman added this to the 3.3 milestone Mar 21, 2024

aaronzo mentioned this pull request Mar 24, 2024

"dispatch" decorator needs documentation for contributors and readers of code #7189

Open

Schefflera-Arboricola mentioned this pull request Apr 10, 2024

Refactoring and enhancing user-facing Backend and Configs docs #7404

Open

cvanelteren pushed a commit to cvanelteren/networkx that referenced this pull request Apr 22, 2024

[DOC, DISPATCH] : updated and added backend.py's docs (networkx#7305)

21366b3

Co-authored-by: Dan Schult <dschult@colgate.edu> Co-authored-by: Ross Barnowski <rossbar@caltech.edu>

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

[DOC, DISPATCH] : updated and added `backend.py`'s docs #7305

[DOC, DISPATCH] : updated and added `backend.py`'s docs #7305

Schefflera-Arboricola commented Feb 19, 2024 •

edited

dschult left a comment

Schefflera-Arboricola commented Feb 28, 2024

aaronzo Mar 4, 2024

dschult Mar 7, 2024

aaronzo Mar 4, 2024

dschult Mar 7, 2024

Schefflera-Arboricola Mar 13, 2024

dschult left a comment

dschult Mar 7, 2024

dschult Mar 7, 2024

dschult commented Mar 7, 2024

dschult left a comment

eriknw Mar 20, 2024

Schefflera-Arboricola Mar 20, 2024 •

edited

rossbar left a comment

		[project.entry-points."networkx.backends"]
		entry_point_name = "your_dispatcher_class"

		Also, you might have seen the `@nx._dispatchable` decorator on many of the NetworkX
		functions. It is used on functions that can have a backend implementation.

-Also, you might have seen the `@nx._dispatchable` decorator on many of the NetworkX
-functions. It is used on functions that can have a backend implementation.
+We are also working on an automatic backend system which could discover which
+backend to use for different situations.
+Also, if you've looked at NetworkX function source code, you might have seen the
+`@nx._dispatchable` decorator on many functions. That decorator makes functions
+check whether to dispatch to a backend implementation or run the NetworkX code.

		Creating a Custom backend
		--------------------------

[DOC, DISPATCH] : updated and added backend.py's docs #7305

[DOC, DISPATCH] : updated and added backend.py's docs #7305

Conversation

Schefflera-Arboricola commented Feb 19, 2024 • edited

dschult left a comment

Choose a reason for hiding this comment

Schefflera-Arboricola commented Feb 28, 2024

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

dschult left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

dschult commented Mar 7, 2024

dschult left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Schefflera-Arboricola Mar 20, 2024 • edited

Choose a reason for hiding this comment

rossbar left a comment

Choose a reason for hiding this comment

[DOC, DISPATCH] : updated and added `backend.py`'s docs #7305

[DOC, DISPATCH] : updated and added `backend.py`'s docs #7305

Schefflera-Arboricola commented Feb 19, 2024 •

edited

Schefflera-Arboricola Mar 20, 2024 •

edited