Assorted documentation improvements

Author: jwodder

README.rst

@@ -54,8 +54,8 @@ Installation
 .. _tqdm: https://tqdm.github.io
 
 
-Example
-=======
+Examples
+========
 
 Get information about a package:
 
@@ -88,3 +88,7 @@ Download a package with a tqdm progress bar:
         client.download_package(
             pkg, path=pkg.filename, progress=tqdm_progress_factory(),
         )
+
+`See more examples in the docs.`__
+
+__ https://pypi-simple.readthedocs.io/en/stable/examples.html

docs/examples.rst

@@ -15,25 +15,28 @@ their metadata "backfilled" in; see
 .. code:: python
 
     # Requirements:
-    #     Python 3.8+
     #     packaging 23.1+
-    #     pypi_simple 1.3+
+    #     pypi_simple 1.5+
 
     from packaging.metadata import parse_email
-    from pypi_simple import PyPISimple
+    from pypi_simple import NoMetadataError, PyPISimple
 
     with PyPISimple() as client:
         page = client.get_project_page("pypi-simple")
         for pkg in page.packages:
-            if pkg.has_metadata:
-                src = client.get_package_metadata(pkg)
-                md, _ = parse_email(src)
-                if deps := md.get("requires_dist"):
-                    print(f"Dependencies for {pkg.filename}:")
-                    for d in deps:
-                        print(f"    {d}")
+            if pkg.has_metadata is not False:
+                try:
+                    src = client.get_package_metadata(pkg)
+                except NoMetadataError:
+                    print(f"{pkg.filename}: No metadata available")
                 else:
-                    print(f"Dependencies for {pkg.filename}: NONE")
+                    md, _ = parse_email(src)
+                    if deps := md.get("requires_dist"):
+                        print(f"Dependencies for {pkg.filename}:")
+                        for d in deps:
+                            print(f"    {d}")
+                    else:
+                        print(f"Dependencies for {pkg.filename}: NONE")
             else:
                 print(f"{pkg.filename}: No metadata available")
             print()

docs/index.rst

@@ -42,8 +42,8 @@ Installation
 .. _tqdm: https://tqdm.github.io
 
 
-Example
-=======
+Examples
+========
 
 Get information about a package:
 
@@ -77,6 +77,7 @@ Download a package with a tqdm progress bar:
             pkg, path=pkg.filename, progress=tqdm_progress_factory(),
         )
 
+:doc:`See more examples in the docs. <examples>`
 
 Indices and tables
 ==================

src/pypi_simple/classes.py

@@ -42,13 +42,13 @@ class DistributionPackage:
     #: The type of the package, or `None` if the filename cannot be parsed.
     #: The recognized package types are:
     #:
-    #: - ``'dumb'``
-    #: - ``'egg'``
-    #: - ``'msi'``
-    #: - ``'rpm'``
-    #: - ``'sdist'``
-    #: - ``'wheel'``
-    #: - ``'wininst'``
+    #: - ``"dumb"``
+    #: - ``"egg"``
+    #: - ``"msi"``
+    #: - ``"rpm"``
+    #: - ``"sdist"``
+    #: - ``"wheel"``
+    #: - ``"wininst"``
     package_type: Optional[str]
 
     #: A collection of hash digests for the file as a `dict` mapping hash

src/pypi_simple/client.py

@@ -326,8 +326,8 @@ def download_package(
         :param bool verify:
             whether to verify the package's digests against the downloaded file
         :param bool keep_on_error:
-            whether to keep (true) or delete (false) the downloaded file if an
-            error occurs
+            whether to keep (true) or delete (false; default) the downloaded
+            file if an error occurs
         :param progress: a callable for constructing a progress tracker
         :param timeout: optional timeout to pass to the ``requests`` call
         :type timeout: float | tuple[float,float] | None

src/pypi_simple/filenames.py

@@ -88,24 +88,24 @@ def parse_filename(
     spelled the same as they appear in the filename; no normalization is
     performed.
 
-    The package type may be any of the following strings:
+    The package type will be one of the following strings:
 
-    - ``'dumb'``
-    - ``'egg'``
-    - ``'msi'``
-    - ``'rpm'``
-    - ``'sdist'``
-    - ``'wheel'``
-    - ``'wininst'``
+    - ``"dumb"``
+    - ``"egg"``
+    - ``"msi"``
+    - ``"rpm"``
+    - ``"sdist"``
+    - ``"wheel"``
+    - ``"wininst"``
 
     Note that some filenames (e.g., :file:`1-2-3.tar.gz`) may be ambiguous as
     to which part is the project name and which is the version.  In order to
-    resolve the ambiguity, the expected value for the project name (*modulo*
-    normalization) can be supplied as the ``project_name`` argument to the
-    function.  If the filename can be parsed with the given string in the role
-    of the project name, the results of that parse will be returned; otherwise,
-    the function will fall back to breaking the project & version apart at an
-    unspecified point.
+    resolve the ambiguity, the expected value for the project name can be
+    supplied as the ``project_name`` argument to the function; it need not be
+    normalized.  If the filename can be parsed with the given string in the
+    role of the project name, the results of that parse will be returned;
+    otherwise, the function will fall back to breaking the project & version
+    apart at an unspecified point.
 
     .. versionchanged:: 1.0.0