If you are interested in contributing to sws (thanks by the way) then this guide should give you all you need to get started. There will be info about sws ' structure, guiding principles, code style information, and more.
Here is everything you need to know about writing code that matches the style of the existing codebase.
There is really only 1 rule for variable names:
DO NOT INCLUDE SINGLE CHARACTER VARIABLE NAMES!
This makes things so much more difficult to debug that it often ends up being better to just re-implement, keep things short, simple, readable and idiomatic.
At a minimum your code must include docstrings for any functions, and inline code for any module global variables (though these should be avoided anyway). The typical format followed is the numpystyle docstrings with at least the attributes, methods, examples, returns/yields and notes sections (where applicable) for both classes and functions.
Ideally you should also include an in-line comment if you are doing any nested iteration, conditionals, or combinations of both, that just quickly explains what's going on.
Here are some of the principles that sws is built on, before submitting a pull request make sure your feature is in line with them (you can also submit an issue to ask before writing it).
- Provide an easy to use cli that saves you writing bash scripts every time you want to do common tasks.
- Provide an extensible API that can be implemented in other projects.
Also take a look at the what is sws? section of the homepage.
Bug Tracking & Roadmap
Source File/Folder Structure
Here is the layout and functions for all the files/folders in the project. I have split it up between functionality, testing/documentation, and Metadata/Manifest files.
All the code that comprises sws' functionality is found in /sws and in the following files:
Includes the code for the
The files in this folder include all the primary logic used by the
Testing & Documentation
This folder contains all the testing files, currently there is only one
primary_test.py which runs a slough of functionality tests.
Includes all the source documentation files for this website (written in markdown and built to HTML using mkdocs).
A chronological list of changes made in various versions of sws, along with their respective public release dates.
A file used by github to give a bit of a blurb about using sws for those who don't want to read the real documentation (good on you by the way).
These are files for doing various maintenance tasks, and storing configurations for different development utilities.
This file is used to specify which files should not include
This file contains the licensing information about the project, which in this case is MIT.
Used to configure various automated processes using nox, these include:
- Building release distributions
- Releasing distributions on PyPi
- Running test suite against a number of python versions (3.5-current)
If anything to do with deployment or releases is failing, this is likely the suspect.
Manifest information for defining sws as a python package. Includes metadata about the package such as version number, the CLI entrypoint, specification of standard installation (and development installation) dependencies, and other metadata required by PyPi.
If you need to modify how python installs sws, this is the file to start with.
/sws/__init__.py & /sws/utilities/__init__.py
This file is used by python to define the /sws & /sws/utilities folder as a python package. You should never need to modify it.