Home

Welcome to the NetworkX wiki!

Design Specification - API Sandbox

Developer Notes

• Configuring your fork with Read the Docs
• Configuring your fork with Travis-CI
• The top of the module: Formatting copyright, authors, etc.
• Formatting docstrings to look nice in code and in sphinx.
• Guidelines for corner cases
• How we tend to handle None
• Explicitly not supporting directed or multigraph in a function

---

Top of Module

Formatting copyright, authors, "the top of the module"

If you use utf-8 unicode characters in your module the first line should be `# -*- coding: utf-8 -*-`.
This is followed by comment lines giving the copyright, a blank comment line and then the authors.
The authors can be formatted as 

    # Authors: name (email) and other_name (email)

or

    # Authors: name (email)
    #          other_name (email)

After the authors, the docstring for the module should appear. Use an `r"""` to start the docstring 
if you use LaTeX math codes. Otherwise use `"""`. The first line should be a one-line description
of the function followed by a blank line and then a description of what the function does.  

After the module docstring you should import python libraries followed by imports of NetworkX features.
Typically this is followed by a definition of `__all__` to list the publicly provided functions of the module.
Two blank lines and you can start your code.   

See [richclub.py](https://github.com/networkx/networkx/blob/master/networkx/algorithms/richclub.py) for an example. It's a good one for sprecial docstring features too.

---

Docstring formatting

• Formatting docstrings to look nice in code and in sphinx. (Generally, follow numpydoc recommendations.)

---

Corner Cases

• Guidelines for corner cases

---

Handling None

• How we tend to handle None

  When checking a value against None use the if var is None: construction. We also use None (as does Python itself) as a null argument to functions where the default argument must be newly computed at runtime. For example, if you use def f(nlist=[]): the list will be created when the function is defined and it will be the same list for all function calls. If you want a new list for each function call use

   def f(nlist=None):
       if nlist is None:
           nlist = []
  

  In some functions we allow nodes to be specified with a default of processing all nodes. We use None to indicate whether an argument was provided or not. Thus, None is special in that it cannot be a node in our graphs. We state that a node can be any hashable other than None.

---

Decorators for Not Implemented

• Explicitly not supporting directed or multigraph in a function:

  Use the decorator not_implemented_for in networkx/utils/decorators.py to designate that a function doesn't accept 'directed', 'undirected', 'multigraph' or 'graph'. The function should have its first argument be the graph object to be checked.

   @nx.not_implemented_for('directed', 'multigraph')
   def function_not_for_MultiDiGraph(G, others):
       # function not for graphs that are directed *and* multigraph
       pass
  
   @nx.not_implemented_for('directed')
   @nx.not_implemented_for('multigraph')
   def function_only_for_Graph(G, others):
       # function not for directed graphs *or* for multigraphs
       pass
  

---