Difference between revisions of "Updating your Extension for 1.0"

From Inkscape Wiki
Jump to navigation Jump to search
(Start page with instructions for extension updating)
 
(add link to auto-generated docs)
(12 intermediate revisions by 4 users not shown)
Line 20: Line 20:


This change is backwards compatible (as long as the user has a fully functioning Inkscape installation).
This change is backwards compatible (as long as the user has a fully functioning Inkscape installation).
Not removing these will result in the extension not being available in Inkscape 1.0 or higher.
=== Changes to parameter definitions ===
There are also some updates to the parameter definitions. While these are intended to be backwards compatible to 0.92, you may wish to review the changes as documented in [https://gitlab.com/inkscape/inkscape/merge_requests/808 MR#808].


== Updating *.py files ==
== Updating *.py files ==
Line 25: Line 32:
=== Collecting the options of the extension ===
=== Collecting the options of the extension ===


#. Instead of <code>inkex.Effect.OptionParser.add_option</code>, your extension should now use <code>inkex.Effect.arg_parser.add_argument</code>.
# Instead of <code>inkex.Effect.OptionParser.add_option</code>, your extension should now use <code>inkex.Effect.arg_parser.add_argument</code>.
#. The 'type' option now works with variables instead of strings. Use <code>int</code> instead of <code>"int"</code> (same for float,...).
# The 'type' option now works with variables instead of strings. Use <code>int</code> instead of <code>"int"</code> (same for float,...).
#. The 'inkbool' type is now <code>inkex.inkbool</code>.
# The 'inkbool' type is now <code>inkex.inkbool</code>.
#. <code>action="store"</code> can be removed.
# <code>action="store"</code> can be removed.


These changes are not backwards compatible. The old options will still work, but are deprecated and should no longer be used when you develop your extension for Inkscape 1.0 or higher.
These changes are not backwards compatible. The old options will still work, but are deprecated and should no longer be used when you develop your extension for Inkscape 1.0 or higher.
Line 34: Line 41:
=== Replace specific functions ===
=== Replace specific functions ===


# <code>pathmodifier</code> is now <code>TODO (see https://gitlab.com/inkscape/extensions/issues/24)</code>.
# <code>pathmodifier.zsort()</code> is now <code>inkex.zsort()</code> (more info: https://gitlab.com/inkscape/extensions/issues/24).
 
Lots more, someone needs to flesh this out.


=== Test run your extension ===
=== Test run your extension ===
Line 41: Line 50:


E.g. <code>inkex.Effect.selected</code> is replaced by <code>inkex.Effect.svg.selected</code> - however, most replacements do not follow this naming scheme translation.
E.g. <code>inkex.Effect.selected</code> is replaced by <code>inkex.Effect.svg.selected</code> - however, most replacements do not follow this naming scheme translation.
These changes are not backwards compatible.


=== Python 3 / Python 2 compatibility ===
=== Python 3 / Python 2 compatibility ===


Test your extension with both Python 2 and Python 3. With the updated extensions, Inkscape does no longer require Python 2, so some users will probably be using Python 3, and may no longer have Python 2 installed on their system. See [[Extension_Interpreters]] for how to set the Python version for your extension.
Test your extension with both Python 2 and Python 3. With the updated extensions, Inkscape does no longer require Python 2, so some users will probably be using Python 3, and may no longer have Python 2 installed on their system. See [[Extension_Interpreters]] for how to set the Python version for your extension (for testing).
 
== Getting your extension added to Inkscape's stock extensions ==
 
Inkscape now has a [https://gitlab.com/inkscape/extensions separate repository for its Python extensions], which is included into Inkscape proper by using a Git submodule.
 
=== Writing tests ===
 
Previously Inkscape didn't require any unit testing for code. You should now write test code, if you expect your module to be included into the Inkscape extensions repository and included in the shipped Inkscape release. In this case, a test suite file should be made in the tests directory for your extension. It should test each aspect of your extension and exercise all assumptions.
 
If you are writing a standalone extension that users will install themselves, there is no strict requirement for tests. But having them will greatly improve your code and your ability to upgrade the code later. You can have tests in your own folders and use the extension's setup.py as a harness to run them (a setup.py file is also useful for installing your python code as a non-inkscape related python module, which might be useful too). See Python documentation for creating packages.
 
=== Documenting your extension ===
 
TODO
 
== API documentation ==
 
The [https://inkscape.gitlab.io/extensions/documentation/ inkex API documentation] collects the inline documentation comments into a single document.
 
== Submitting your extension for inclusion ==
 
Visit https://gitlab.com/inkscape/extensions, fork the repository, and create a merge request on GitLab.
 
[[Category:Extensions]]

Revision as of 10:29, 28 August 2019

This is a preliminary and incomplete list of actions to take for updating Python extensions for Inkscape 1.0:

Updating *.inx files

Remove dependency listings

Remove the dependency listings for the following modules:

  • bezmisc.py
  • coloreffect.py
  • cspsubdiv.py
  • cubicsuperpath.py
  • ffgeom.py
  • inkex.py (removal not strictly required)
  • pathmodifier.py
  • simplepath.py
  • simplestyle.py
  • simpletransform.py
  • more?

This change is backwards compatible (as long as the user has a fully functioning Inkscape installation). Not removing these will result in the extension not being available in Inkscape 1.0 or higher.


Changes to parameter definitions

There are also some updates to the parameter definitions. While these are intended to be backwards compatible to 0.92, you may wish to review the changes as documented in MR#808.


Updating *.py files

Collecting the options of the extension

  1. Instead of inkex.Effect.OptionParser.add_option, your extension should now use inkex.Effect.arg_parser.add_argument.
  2. The 'type' option now works with variables instead of strings. Use int instead of "int" (same for float,...).
  3. The 'inkbool' type is now inkex.inkbool.
  4. action="store" can be removed.

These changes are not backwards compatible. The old options will still work, but are deprecated and should no longer be used when you develop your extension for Inkscape 1.0 or higher.

Replace specific functions

  1. pathmodifier.zsort() is now inkex.zsort() (more info: https://gitlab.com/inkscape/extensions/issues/24).

Lots more, someone needs to flesh this out.

Test run your extension

Many functions, when run, will still work, but they will give you a deprecation warning, with instructions what to replace them by.

E.g. inkex.Effect.selected is replaced by inkex.Effect.svg.selected - however, most replacements do not follow this naming scheme translation.

These changes are not backwards compatible.

Python 3 / Python 2 compatibility

Test your extension with both Python 2 and Python 3. With the updated extensions, Inkscape does no longer require Python 2, so some users will probably be using Python 3, and may no longer have Python 2 installed on their system. See Extension_Interpreters for how to set the Python version for your extension (for testing).

Getting your extension added to Inkscape's stock extensions

Inkscape now has a separate repository for its Python extensions, which is included into Inkscape proper by using a Git submodule.

Writing tests

Previously Inkscape didn't require any unit testing for code. You should now write test code, if you expect your module to be included into the Inkscape extensions repository and included in the shipped Inkscape release. In this case, a test suite file should be made in the tests directory for your extension. It should test each aspect of your extension and exercise all assumptions.

If you are writing a standalone extension that users will install themselves, there is no strict requirement for tests. But having them will greatly improve your code and your ability to upgrade the code later. You can have tests in your own folders and use the extension's setup.py as a harness to run them (a setup.py file is also useful for installing your python code as a non-inkscape related python module, which might be useful too). See Python documentation for creating packages.

Documenting your extension

TODO

API documentation

The inkex API documentation collects the inline documentation comments into a single document.

Submitting your extension for inclusion

Visit https://gitlab.com/inkscape/extensions, fork the repository, and create a merge request on GitLab.