Metadata-Version: 2.4
Name: openmairie.devtools
Version: 1.3.0
Summary: openMairie Developer Tools
Home-page: http://www.openmairie.org/framework
Author: openMairie
Author-email: contact@openmairie.org
License: GPL
Project-URL: Source, https://gitlab.com/openmairie/openmairie.devtools/
Keywords: openMairie
Platform: any
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: License :: OSI Approved :: GNU General Public License (GPL)
Requires-Dist: setuptools
Requires-Dist: jinja2
Requires-Dist: unidecode
Dynamic: author
Dynamic: author-email
Dynamic: classifier
Dynamic: description
Dynamic: home-page
Dynamic: keywords
Dynamic: license
Dynamic: platform
Dynamic: project-url
Dynamic: requires-dist
Dynamic: summary

openmairie.devtools
===================

openMairie Developer Tools

.. image:: https://img.shields.io/pypi/v/openmairie.devtools.svg
    :target: https://pypi.python.org/pypi/openmairie.devtools/
    :alt: Latest PyPI version

.. contents::

Introduction
------------

openmairie.devtools is a collection of command-line programs to handle tasks on
`openMairie Framework <http://www.openmairie.org/framework/>`_ based projects.
Mainly initialize environment, run tests, release a project, ...


Installation
------------

You just need `pip <https://pip.pypa.io>`_ ::

    pip install openmairie.devtools

om-logo specifics
#################

For PNG rendering, Inkskape should be available. 
On Debian-based OS (Ubuntu, etc) ::

    sudo apt-get install inkscape

For other OS, please visit ::

    https://inkscape.org/en/release

You should have the right font (**Caviar Dream**) available on your system.
Get it there ::

    https://www.fontsquirrel.com/fonts/download/Caviar-Dreams


Available commands
------------------

om-tests
########

Should be run from the *tests* folder of your project and allow you to
initialize your test environment, to run all tests suites or to run only one
tests suite.

om-svnexternals
################

Should be run from the root of your project.  It scans for ``EXTERNALS.txt``
files and resolves each entry using the following strategy:

1. **GitLab package registry** — the SVN URL is parsed to derive a package
   name and version.  If a matching archive exists in the
   `openmairie/framework-openmairie <https://gitlab.com/openmairie/framework-openmairie/-/packages>`_
   generic package registry, it is downloaded and extracted.
2. **SVN export** — if no archive is found, a classic
   ``svn export --force --ignore-externals`` is performed and any nested
   ``EXTERNALS.txt`` discovered inside the export is resolved recursively.

Two URL patterns are recognised:

- **Externals** (``externals--`` prefixed packages)::

    .../externals/fpdf/tags/1.8.5/             → externals--fpdf          1.8.5
    .../externals/pear/pear-core/tags/v1.10.12 → externals--pear--pear-core v1.10.12
    .../externals/om-theme/kied/tags/2.0.0     → externals--om-theme--kied 2.0.0

- **Framework** (``openmairie_exemple``) — maps to the single package
  ``externals--framework-openmairie``.  The bundled archive (with resolved
  sub-externals) is preferred over the bare one::

    .../openmairie_exemple/tags/4.11.0-a16/core → core-bundle.tar.gz then core.tar.gz
    .../openmairie_exemple/tags/4.11.0-a16/lib  → lib-bundle.tar.gz  then lib.tar.gz

**Local cache**

Downloaded archives are cached locally so subsequent runs are near-instant.
The cache directory follows the
`XDG Base Directory Specification <https://specifications.freedesktop.org/basedir-spec/latest/>`_::

    $XDG_CACHE_HOME/om-devtools/packages/
    # or, when XDG_CACHE_HOME is not set:
    ~/.cache/om-devtools/packages/

**Options**

``-N``, ``--no-cache``
    Bypass the local cache and force re-download from the registry.  The
    downloaded archives are still stored in the cache for future use.

**Usage** ::

    cd /path/to/your/project
    om-svnexternals            # normal run (uses cache)
    om-svnexternals -N         # force re-download

om-logo
#######

This command allows you to generate SVG and PNG logo for your openMairie
application, according to design's guideline available here ::

    http://www.openmairie.org/communaute/ressources-graphiques/openmairie-identite-visuelle.pdf

Full documentation is available from the help command ::

    om-logo --help


Configuration
-------------

Global configuration is read from
``~/.om-devtools/config.cfg``.  The legacy path
``~/.om-tests/config.cfg`` is still supported but deprecated — a warning is
printed on stderr when it is used.

Example ``config.cfg``::

    [browser]
    src_path = /path/to/browser/source
    dest_path = /path/to/browser/destination



Changelog
=========

1.3.0 (2026-03-30)
------------------

- om-tests: ``runall`` command now excludes the ``dev`` tag by default.
  [epontagnier]
- om-svnexternals: resolve externals from GitLab generic package registry
  instead of svn export when the archive is available.  Falls back to
  svn export when not found.
  [flohcim]
- om-svnexternals: add local cache for downloaded archives
  (``~/.cache/om-devtools/packages/``).  Use ``-N`` / ``--no-cache``
  to force re-download.
  [flohcim]
- om-svnexternals: use ``svn export --force --ignore-externals`` and
  recursively resolve nested ``EXTERNALS.txt`` files.
  [flohcim]
- om-svnexternals: support framework URLs (``openmairie_exemple``) mapped to
  ``externals--framework-openmairie`` package with bundle priority.
  [flohcim]
- Rename configuration directory from ``~/.om-tests/`` to
  ``~/.om-devtools/``.  The legacy path is still read with a
  deprecation warning.
  [flohcim]


1.2.0 (2025-05-28)
------------------

- Fixed documentation for pabot.
  [rasseum]
- Added two contributors.
  [rasseum]
- Note: Version 1.1.1 should have been named 1.2.0. This 1.2.0 version restores
  proper versioning by correcting several aspects.
  [rasseum]

1.1.1 (2025-04-24)
------------------

- Add pabot to openmairie.devtools.
  [rasseum]


1.1.0 (2023-10-08)
------------------

- Use robot and not pybot command anymore.
  [flohcim]


1.0.0 (2022-05-10)
------------------

- Python 3 support only.
  [flohcim, tiazma]


0.4.0 (2018-04-10)
------------------

- Add 'additional_sql' option config to om-tests.
  [flohcim]


0.3.1 (2018-01-10)
------------------

- Removed unnecessary jinja2 env options
  [tiazma]


0.3.0 (2018-01-10)
------------------

- Added om-logo, application logo generation
  [tiazma]


0.2.2 (2017-11-25)
------------------

- Remove the externals was breaking travis CI.
  [flohcim]

0.2.1 (2017-11-24)
------------------

- Filename of EXTERNALS.txt file parsed was missing.
  [flohcim]

0.2.0 (2017-11-24)
------------------

- Add om-svnexternals script.
  [flohcim]


0.1 (2017-11-23)
----------------

- Initial release as a python package.
  [flohcim, fmichon, jymadier, mbroquet, nhaye, NHaye, nmeucci, oc1n, softime,
  stimezouaght, tiazma]


Contributors
============

* Florent Michon <flohcim@gmail.com> [flohcim][fmichon]
* Grégory Malvolti <gmalvolti@atreal.fr> [gmalvolti]
* Jean-Yves Madier de Champvermeil <> [jymadier]
* Matthias Broquet <mbroquet@atreal.fr> [mbroquet][tiazma]
* Nicolas Haye <> [nhaye][NHaye]
* Nicolas Meucci <> [nmeucci][oc1n]
* Sofien Timezouaght <> [softime][stimezouaght]
* Rabah Asseum <rasseum@atreal.fr> [rasseum]
* Sébastien Dethyre <> [sdethyre]
