Creating an extension¶
Once an new filesystem implemented, it is possible to distribute as a
subpackage contained in the
fs namespace. Let’s say you are trying
to create an extension for a filesystem called AwesomeFS.
For the sake of clarity, and to give a clearer sight of the Pyfilesystem2 ecosystem, your extension should be called fs.awesome or fs.awesomefs, since PyPI allows packages to be namespaced. Let us stick with fs.awesome for now.
The extension must have either of the following structures:
└── fs.awesome └── fs.awesome ├── fs ├── fs │ ├── awesomefs.py │ ├── awesomefs │ └── opener | | ├── __init__.py │ └── awesomefs.py | | ├── some_file.py └── setup.py | | └── some_other_file.py │ └── opener │ └── awesomefs.py └── setup.py
The structure on the left will work fine if you only need a single file to implement AwesomeFS, but if you end up creating more, you should probably use the structure on the right (create a package instead of a single file).
Do NOT create
fs/opener/__init__.py ! Since
those files are vital to the main Pyfilesystem2 package, including them
could result in having your extension break the whole Pyfilesystem2
package when installing.
Refer to the setuptools documentation
to see how to write a
setup.py file. There are only a few things that
should be kept in mind when creating a Pyfilesystem2 extension. Make sure that:
- the name of the package is the namespaced name (fs.awesome with our example).
fs.awesomefspackages are included. Since you can’t create
fs/opener/__init__.py, setuptools won’t be able to find your packages if you use
setuptools.find_packages, so you will have to include packages manually.
fsis in the
install_requireslist, in order to always have Pyfilesystem2 installed before your extension.
To ensure your new filesystem can be reached through the generic
you must declare a
Opener in the
fs/opener directory. With our example,
create a file called
awesomefs.py containing the definition of
AwesomeFSOpener inside of the
fs/opener directory. This will
allow your Filesystem to be created directly through
having to import your extension first !
Use relative imports whenever you try to access to a resource in the
fsmodule or any of its submodules.
Keep track of your achievements ! Add
__license__variables to your project (either in
fs/awesomefs/__init__.pydepending on the chosen structure), containing:
the version of the extension (use Semantic Versioning if possible !)
the license of the subpackage