Contents

• Introduction
• Structure of PySAL Organizational account
  • Relationships
  • Use cases
    • All in one installation
    • Pick and choose
• Package naming conventions
• Standards for Top-Level PySAL repositories
  • Code layout
  • Testing conventions
  • Documentation

This is a concrete proposal in response to PEP 12: Refactor PySAL Code Base that relies on submodules.

The public PySAL repositories would consist of

The pysal package would have each of the remaining packages as submodules.

Each of the remaining packages, other than pysal-core, would have pysal-core as a dependency via import.

This would facilitate different types of use cases for the library as well as the individual packages.

pip install pysal

or

conda install pysal

pip install pysal-points pysal-viz

or

conda install pysal-points pysal-viz

In some cases (i.e., pysal-points) the name has been extended to differentiate pysal from a general library name (points). This is because each of the repositories should be a package in its own right and thus installable via pip where an unambiguous name is required.

To faciliate use of the top level projects within the PySAL meta-package, the former repositories may consider the following conventions.

package_name/
	__init__.py
	source1.py
	source2.py
	.
	.
	sourcek.py
	setup.py
	.travis.yml
	copying.md
	doc/
	tests/
	README.md

PySAL has relied on nose for integration tests, so the directory structure given above would allow for integration testing under the new organization scheme.

In contrast to the current approach where documentation is built across all the submodules to generate the PySAL documentation, this new model would have lighter weight documentation for the meta project that would simply link to the documentation of the individual modules. Maintainers would be reponsible for the documentation of each module.

This example uses the points-contrib module:

 
git clone git@github.com:sjsrey/pysal.git pysal-copy
mv pysal-copy pysal-points
cd pysal-points
git fetch origin
git branch -a
git checkout -b points origin/points_contrib
git filter-branch --subdirectory-filter pysal/contrib/points -- --all