.. _dev_making_changes: **************************** Making Changes to mpas_tools **************************** New python functions and modules (``.py`` files) can be added within the ``conda_package/mpas_tools``. These will automatically be part of the ``mpas_tools`` package. New directories with python modules should include an ``__init__.py`` file (which can be empty) to indicate that they are also part of the package. Entry Points ============ The best way to add new "scripts" to the package is to add a function without any arguments somewhere in the package, and then to add it as an "entry point" both in ``conda_package/setup.py`` and ``conda_package/recipe/meta.yaml``. As an example, the entry point ``planar_hex`` is defined in ``setup.py`` as: .. code-block:: python setup(name='mpas_tools', ... entry_points={'console_scripts': ['planar_hex = mpas_tools.planar_hex:main', ... and in ``meta.yaml`` as: .. code-block:: build: number: 0 entry_points: - planar_hex = mpas_tools.planar_hex:main When the package is installed in a conda environment, a stub script ``planar_hex`` will be in the user's path that will call the function ``main()`` in the module ``mpas_tools.planar_hex``: .. code-block:: python def main(): parser = argparse.ArgumentParser( description=__doc__, formatter_class=argparse.RawTextHelpFormatter) parser.add_argument('--nx', dest='nx', type=int, required=True, help='Cells in x direction') ... args = parser.parse_args() make_planar_hex_mesh(args.nx, args.ny, args.dc, args.nonperiodic_x, args.nonperiodic_y, args.outFileName) As you can see, the function pointed to by the entry point can used to parse command-line arguments, just as a "normal" python script would do By convention, entry points do not typically include the ``.py`` extension. Dependencies ============ If you changes introduce new dependencies, these need to be added to both the recipe for the conda package in ``conda_package/recipe/meta.yaml`` and to the text file describing the development environment, ``conda_package/dev-spec.txt``. In ``meta.yaml``, add these changes in alphabetical order to the ``run`` section of ``requirements``: .. code-block:: yaml requirements: ... run: - python - affine ... These requirements *must* be on the ``conda-forge`` anaconda channel. If you need help with this, please contact the developers. Add the new dependencies in alphabetical order to ``dev-speck.txt`` under the ``# Base`` comment: .. code-block:: none ... # This file may be used to create an environment using: # $ conda create --name --file # Base python>=3.8 cartopy ... Updating the Version ==================== Before a release of the package, the version of ``mpas_tools`` needs to be updated in 3 places. First, in ``conda_package/mpas_tools/__init__.py``: .. code-block:: python __version_info__ = (0, 6, 0) __version__ = '.'.join(str(vi) for vi in __version_info__) Increment ``__version_info__`` (major, minor or micro version, depending on what makes sense). Second, the version in the conda recipe (``conda_package/recipe/meta.yaml``) needs to match: .. code-block:: {% set name = "mpas_tools" %} {% set version = "0.6.0" %} Third, Add the new version to the :ref:`versions` in the documentation. .. code-block:: `v0.6.0`_ `0.6.0`_ ================ =============== ... .. _`v0.6.0`: ../0.6.0/index.html .. _`0.6.0`: https://github.com/MPAS-Dev/MPAS-Analysis/tree/0.6.0 The new links won't be valid until a new release is made and Azure Pipelines has generated the associated documentation. Eventually, it should be possible to do this automatically but that has not yet been implemented.