support for user settings

CHANGELOG.md

@@ -1,5 +1,12 @@
 # whl2conda changes
 
+## [24.5.0] - 2024-5-5
+### Features
+* Added persistent user settings for:
+    * default conda format
+    * whether to automatically update stdrenames table
+    * specify aliases for extra pypi indexes
+
 ## [24.4.0] - 2024-4-14
 ### Changes
 * Only use classic installer in `whl2conda install` environments if 

Makefile

@@ -129,6 +129,11 @@ html-coverage: htmlcov/index.html
 open-coverage: htmlcov/index.html
 	$(OPEN) $<
 
+# TODO-
+#   add target for running tests on built wheel or conda package
+#   use tox?
+#   Needs test dependencies: pytest, build, hatchling
+
 #
 # Documentation targets
 #

doc/guide/basic-usage.md

@@ -43,6 +43,21 @@ to do this download for you, for example:
 $ whl2conda convert --from-pypi 'some-package ==1.2.3'
 ```
 
+The `--from-index` option expects either the full URL of the pypi index to
+download from or an alias, which may either be taken from a repository entry
+in your [~/.pypirc][pypirc] file or from an entry in the users persistent
+whl2conda configuration. For instance, you could register a new index using
+a command like:
+
+```bash
+$ whl2conda config --set pypi-index.myindex https://myindex.com/pypi/
+```
+and then convert using:
+
+```bash
+$ whl2conda convert --from-index myindex 'some-package'
+```
+
 ## Building from project directories
 
 If you are creating a conda package for your own python project that uses
@@ -85,11 +100,19 @@ Reading mypackage-1.2.3-py3-none-any.whl
 Writing mypackage-1.2.3-py_0.tar.bz2
 ```
 
+You can change the default output format through a persistent user setting, .e.g:
+
+```bash
+$ whl2conda config --set conda-format V1
+```
+
 You can also specify the format `tree` to generate the conda package
 as a directory tree, so that you can examine its contents for
 debugging purposes.
 
 [pip-download]: https://pip.pypa.io/en/stable/cli/pip_download/
 [pip-wheel]: https://pip.pypa.io/en/stable/cli/pip_wheel/
 [pypi]: https://pypi.org
+[pypirc]: https://packaging.python.org/en/latest/specifications/pypirc/
+
 

doc/guide/renaming.md

@@ -53,6 +53,13 @@ there is package new to [conda-forge] that may have appeared since installing
 $ whl2conda --update-std-renames
 ```
 
+You can also configure whl2conda to automatically update the standard rename
+mappings prior to operations that require via a persistent user setting:
+
+```bash
+$ whl2conda config --set auto-update-std-renames true
+```
+
 The cache file is kept in a location in your user directory that is specific 
 to your operating system:
 

doc/internal/release-process.md

@@ -0,0 +1,89 @@
+# whl2conda release process
+
+The release process is currently entirely manual:
+
+## Prerequistes
+
+* [ ] Tests should be added for all new features or changed behavior.
+* [ ] All tests must pass locally and in CI jobs.
+* [ ] Significant changes should be described in `CHANGELOG.md`
+* [ ] New features and changes must be documented.
+
+## Release procedure
+
+### Package release
+
+1. Update version in `src/whl2conda/VERSION`.
+
+    We use calver scheme of the form `YY.M.<patch>`, so the first release
+    in June 2024 would be `24.6.0`. Increment the last number if there already
+    was a release in the month. It may be surprising to users to see signficant
+    changes introduced in a patch release, so it probably is best to delay such
+    releases to the next month.
+
+2. Update the checked in copy of the standard renames table:
+
+    ```bash
+    $ make update-std-rename
+    ```
+
+    commit the changed `src/whl2conda/api/stdrename.json` file.
+
+3. After all changes have been merged, check out `main` branch.
+
+4. Build wheel and conda package
+
+    ```bash
+    $ make build-wheel
+    ```
+5. Test built packages (*optional but recommended*)
+
+    Test the generated wheel and conda package by installing locally and
+    testing manually or by running `pytest test` in environment with installed
+    package.
+
+6. When everything is ok, upload to pypi:
+
+    ```bash
+    $ make check-upload
+    $ make upload
+    ```
+
+    This assumes that you have permission to upload and have configured a token
+    in you `~/.pypirc`.
+
+7. Watch for and accept merge request from conda-forge
+
+    Sometime after the pypi upload, the whl2conda-feedstock on conda-forge
+    will get an automatically generated merge request, and feedstock maintainers
+    will get a notification. Usually this happens within a day of the pypi upload. 
+
+    If there are no breaking runtime dependencies, then nothing needs to be done
+    other than to accept the merge request. If dependencies have changed, it will
+    be necesssary to update the feedstock's conda-recipe.
+
+### Documentation release
+
+1. Build and review current documentation
+
+    ```bash
+    $ make clean-doc
+    $ make doc
+    $ make doc-serve
+    ```
+
+2. Deploy version to gh-pages git branch using mike and verify
+
+    ```bash
+    $ make doc-deploy
+    $ make doc-serve-all
+    ```
+
+3. Upload gh-pages
+
+    ```bash
+    $ make doc-upload
+    ```
+
+    The CI job will eventually install this at https://zuzukin.github.io/whl2conda/
+

doc/reference/api/settings.md

@@ -0,0 +1,3 @@
+# whl2conda.settings
+
+:::whl2conda.settings

doc/reference/links.md

@@ -17,8 +17,8 @@
 * [Wheel metadata 1.1 (PEP 314)](https://peps.python.org/pep-0314/)
 * [Wheel metadata 1.2 (PEP 345)](https://peps.python.org/pep-0345/)
 * [Wheel metadata 2.1 (PEP 566)](https://peps.python.org/pep-0566/)
-* [Wheel metadata 2.2 (PEP 643)](https://peps.python.org/pep-643/)
-* [Wheel metadata 2.3 (PEP 685)](https://peps.python.org/pep-685/)
+* [Wheel metadata 2.2 (PEP 643)](https://peps.python.org/pep-0643/)
+* [Wheel metadata 2.3 (PEP 685)](https://peps.python.org/pep-0685/)
 
 ## pyproject.toml metadata format:
 

environment.yml

@@ -22,7 +22,7 @@ dependencies:
   - types-pyyaml >=6.0
   # documentation
   - black >=23.12
-  - mike >=1.1,<2.0
+  - mike >=2.0,<3.0
   - mkdocs >=1.5,<2.0
   - mkdocstrings-python >=1.7,<2.0
   - mkdocs-material >9.1

mkdocs.yml

@@ -6,6 +6,8 @@ site_dir: site
 site_author: Christopher Barber
 repo_name: GitHub
 copyright: Copyright © 2023 Christopher Barber
+exclude_docs: |
+  /internal/
 
 # https://squidfunk.github.io/mkdocs-material/setup/changing-the-colors/
 #extra_css:
@@ -30,8 +32,8 @@ theme:
   hljs_languages:
     python
     json
-  logo: whl2conda.svg
-  favicon: whl2conda.svg
+  logo: whl2conda.jpg
+  favicon: whl2conda.jpg
   palette:
     - media: "(prefers-color-scheme: light)"
       scheme: default
@@ -113,6 +115,3 @@ markdown_extensions:
           class: mermaid
 #          format: !!python/name:pymdownx.superfences.fence_code_format
   - attr_list
-  - pymdownx.emoji:
-      emoji_index: !!python/name:materialx.emoji.twemoji
-      emoji_generator: !!python/name:materialx.emoji.to_svg

src/whl2conda/VERSION

@@ -1 +1,3 @@
-24.4.0
+24.5.0
+
+

src/whl2conda/api/converter.py

@@ -313,14 +313,16 @@ def __init__(
         self,
         wheel_path: Path,
         out_dir: Path,
+        *,
+        update_std_renames: bool = False,
     ):
         self.logger = logging.getLogger(__name__)
         self.wheel_path = wheel_path
         self.out_dir = out_dir
         self.dependency_rename = []
         self.extra_dependencies = []
         # TODO - option to ignore this
-        self.std_renames = load_std_renames()
+        self.std_renames = load_std_renames(update=update_std_renames)
 
     def convert(self) -> Path:
         """