Refactor the purl2url functions and utilities #42 (#102)

* Refactor purl2url into get_repo_url and get_download_url #42

Signed-off-by: Thomas Druez <tdruez@nexb.com>

* Add support for nuget in purl2url.get_download_url #42

Signed-off-by: Thomas Druez <tdruez@nexb.com>

* Add get_inferred_urls function to return all inferred URLs #42

Signed-off-by: Thomas Druez <tdruez@nexb.com>

* Include the `version_prefix` as a qualifier to infer valid URLs #42

Signed-off-by: Thomas Druez <tdruez@nexb.com>

* Fix formatting with black #42

Signed-off-by: Thomas Druez <tdruez@nexb.com>

* Add support for qualifiers in purl_from_pattern #42

Qualifier `download_url` is now supported in build_github_download_url

Signed-off-by: Thomas Druez <tdruez@nexb.com>

* Return the download_url qualifier when available in get_download_url #42

Signed-off-by: Thomas Druez <tdruez@nexb.com>

* Add changelog entry #42

Signed-off-by: Thomas Druez <tdruez@nexb.com>

Author: tdruez

CHANGELOG.rst

@@ -1,6 +1,25 @@
 Changelog
 =========
 
+next ()
+-------
+
+- Refactor the purl2url functions and utilities #42
+
+  - Split purl2url into `get_repo_url()` and `get_download_url()` returning
+    accordingly a "Repository URL" and a "Download URL".
+  - A new `get_inferred_urls` function is available to get return all
+    inferred URLs (repository and download) values.
+  - Add support in purl2url for npm, pypi, hackage, and nuget.
+  - Package URL qualifiers can now be provided to `purl_from_pattern()`.
+  - The `download_url` qualifier is returned in `get_download_url()` when available.
+
+- Usage of `purl2url.purl2url` and `purl2url.get_url` is still available for
+  backward compatibility but should be migrated to `purl2url.get_repo_url`.
+
+- Include the `version_prefix` ("v" or "V") as a qualifier in build_github_purl #42
+  This allow to infer valid URLs in the context of purl2url.
+
 
 0.10.3 (2022-09-15)
 -------------------

README.rst

@@ -9,7 +9,6 @@ Join the discussion at https://gitter.im/package-url/Lobby or enter a ticket for
 
 License: MIT
 
-
 Tests and build status
 ======================
 
@@ -19,46 +18,79 @@ Tests and build status
 | |ci-tests|           |
 +----------------------+
 
+Install
+=======
+::
+
+    pip install packageurl-python
 
 Usage
 =====
-
 ::
 
     >>> from packageurl import PackageURL
+
     >>> purl = PackageURL.from_string("pkg:maven/org.apache.commons/io@1.3.4")
     >>> print(purl.to_dict())
     {'type': 'maven', 'namespace': 'org.apache.commons', 'name': 'io', 'version': '1.3.4', 'qualifiers': None, 'subpath': None}
+
     >>> print(purl.to_string())
     pkg:maven/org.apache.commons/io@1.3.4
+
     >>> print(str(purl))
     pkg:maven/org.apache.commons/io@1.3.4
+
     >>> print(repr(purl))
     PackageURL(type='maven', namespace='org.apache.commons', name='io', version='1.3.4', qualifiers={}, subpath=None)
 
+Utilities
+=========
 
-Other utilities:
+Django models
+^^^^^^^^^^^^^
 
-- packageurl.contrib.django_models.PackageURLMixin is a Django abstract model mixin to use Package URLs in Django.
-- packageurl.contrib.purl2url.get_url(purl) returns the download URL inferred from a Package URL.
-- packageurl.contrib.url2purl.get_purl(url) returns a Package URL inferred from URL.
+`packageurl.contrib.django_models.PackageURLMixin` is a Django abstract model mixin to use Package URLs in Django.
 
+URL to PURL
+^^^^^^^^^^^
+
+`packageurl.contrib.url2purl.get_purl(url)` returns a Package URL inferred from an URL.
 
-Install
-=======
 ::
 
-    pip install packageurl-python
+    >>> from packageurl.contrib import url2purl
+    >>> url2purl.get_purl("https://github.com/package-url/packageurl-python")
+    PackageURL(type='github', namespace='package-url', name='packageurl-python', version=None, qualifiers={}, subpath=None)
+
+PURL to URL
+^^^^^^^^^^^
+
+- `packageurl.contrib.purl2url.get_repo_url(purl)` returns a repository URL inferred from a Package URL.
+- `packageurl.contrib.purl2url.get_download_url(purl)` returns a download URL inferred from a Package URL.
+- `packageurl.contrib.purl2url.get_inferred_urls(purl)` return all inferred URLs (repository, download) from a Package URL.
+
+::
+
+    >>> from packageurl.contrib import purl2url
+
+    >>> purl2url.get_repo_url("pkg:rubygems/bundler@2.3.23")
+    "https://rubygems.org/gems/bundler/versions/2.3.23"
+
+    >>> purl2url.get_download_url("pkg:rubygems/bundler@2.3.23")
+    "https://rubygems.org/downloads/bundler-2.3.23.gem"
+
+    >>> purl2url.get_inferred_urls("pkg:rubygems/bundler@2.3.23")
+    ["https://rubygems.org/gems/bundler/versions/2.3.23", "https://rubygems.org/downloads/bundler-2.3.23.gem",]
 
 Run tests
 =========
 
-install::
+Install test dependencies::
 
     python3 thirdparty/virtualenv.pyz --never-download --no-periodic-update .
     bin/pip install -e ."[test]"
 
-run tests::
+Run tests::
 
     bin/py.test tests
 
@@ -91,7 +123,6 @@ Make a new release
     bin/twine upload dist/*
 
 
-
 .. |ci-tests| image:: https://github.com/package-url/packageurl-python/actions/workflows/ci.yml/badge.svg?branch=main
     :target: https://github.com/package-url/packageurl-python/actions/workflows/ci.yml
     :alt: CI Tests and build status