hugodahl/UpdateProcess.md

## UpdateProcess.md

      
    Raw
  

              UpdateProcess.md
            
          
    Moving a CircuitPython from a module to a Package

The Clinical Steps

Code changes


Create a directory with the name adafruit_library where "library" is the name

Note: CASE matters. Make it all lowercase


Add an __init__.py file to the directory

Let Python know that the directory can be imported
File can be empty


Update setup.py

Change py_modules=[...] to 'packages=[...]`


Move the existing module to the new directory

Use git mv to keep the full history
Drop the "adafruit" prefix from the filenames
git mv adafruit_filename.py ./adafruit_library/filename.py
Update the name of the module at the top of the file to its new name. This is for Sphinx to be able to reference the module.

For example, if the library was "adafruit_filename", it would change as below...


SPDX-License....
`adafruit_filename`  #  <--- This changes...
`filename`           #  <--- ...to this.
================================================================================

Documentation Changes

The documentation is generated programatically from the file and directory layout and content. We've handled the contents in the previous section, so now we need to handle the update in directory structure. Fortunately, this is a simple change to make.

Open the file in the path /docs/api.rst from the root of the repository
Locate a line with text similar to .. automodule:: adafruit_library

Note: There should be only one such line, but if there are multiple, update those as well


Update the line(s) to reflect the new directory structure, replacing the path separator, either \/ or \\ with a period (.)

Using the same example as above, the value adafruit_filename would be updated to adafruit_library.filename


The Follow-Through

After the library's been updated, the next portion which needs to be updated and not overlooked, are the examples. These are typically found in the /examples directory, in the root of the repository. This typically involves updating the import statement(s) from something much like import adafruit_library to the new structure similar to from adafruit_library import filename or from adafruit_library.filename import module
Test!

This is a good place to make sure all the changes have taken, and the code still works as expected. If it all works with the updated paths and imports, this is a good place to commit your changes and save it in a good state.
Note: You should also try to generate the HTML documentation to make sure it all works as well. The instructions to do so can be found on the Creating and sharing a CircuitPython Library Learn guide, in the Sharing docs on ReadTheDocs section..
When adding a new file to the package

If you're adding a completely new module, which has no dependency on other modules, nothing changes. However, if you're enhancing a class with a subclass, refactoring out a base class, or need to access functionality in the other modules, follow these steps...


Using an import from within the same package

from . import [...]


Update any examples to follow the same format as in the The Follow-Through section above.

import [package_name].[library]
from [library] import [...] to from [package_name].[library] import [...]