Packages from remote unavailable

I'm not sure if this is an issue with the documentation, my method, or a bug. This started as an issue seen on our local pulp repository running a slightly older version; I've now tested it on the latest docker images and am still having no joy.

I have a package, package with a dependency on dependency, available in PyPI and want to be able to install package like this:

$ pip install --index-url https://pulp/pulp/content/foo/simple/ package

What happens is an error something like this:

...
  Looking in indexes: https://pulp/pulp/content/foo/simple/
  ERROR: Could not find a version that satisfies the requirement dependency>=1.0.0 (from versions: none)
  ERROR: No matching distribution found for dependency>=1.0.0
...
ERROR: Could not find a version that satisfies the requirement package (from versions: 1.0.0)
ERROR: No matching distribution found for package

Note that pip finds (and downloads) package successfully - it's only the dependencies (which are not in the repository foo) which cause an issue.
The documentation here is not especially clear. My understanding is that it should be sufficient to perform the following:

$ pulp python remote create --name pypi-excludes --url https://pypi.org/ --excludes '["package"]'
$ pulp python repository sync --name foo --remote pypi-excludes

Once the task completes, I notice that no new repository version is created. Nevertheless, something happened: if I inspect the docker volumes, they now have information from the index. I see that the the remote has been assigned to the repository (I also tried to do this by hand, but the docs say the sync does it):

$ pulp python repository show --name foo                                                                                                                                   
{
  "pulp_href": "/pulp/api/v3/repositories/python/python/6f6d94b0-9906-4b34-ba90-2973ccb767d9/",
  "pulp_created": "2021-05-27T11:27:29.503126Z",
  "versions_href": "/pulp/api/v3/repositories/python/python/6f6d94b0-9906-4b34-ba90-2973ccb767d9/versions/",
  "pulp_labels": {},
  "latest_version_href": "/pulp/api/v3/repositories/python/python/6f6d94b0-9906-4b34-ba90-2973ccb767d9/versions/2/",
  "name": "foo",
  "description": null,
  "remote": "/pulp/api/v3/remotes/python/python/051db320-ad11-4e1d-ac84-8d9002f13720/"
}

and here is the repository version:

$ pulp python repository version show --repository foo
{
  "pulp_href": "/pulp/api/v3/repositories/python/python/6f6d94b0-9906-4b34-ba90-2973ccb767d9/versions/2/",
  "pulp_created": "2021-05-27T17:43:42.798016Z",
  "number": 2,
  "base_version": null,
  "content_summary": {
    "added": {
      "python.python": {
        "count": 1,
        "href": "/pulp/api/v3/content/python/packages/?repository_version_added=/pulp/api/v3/repositories/python/python/6f6d94b0-9906-4b34-ba90-2973ccb767d9/versions/2/"
      }
    },
    "removed": {},
    "present": {
      "python.python": {
        "count": 2,
        "href": "/pulp/api/v3/content/python/packages/?repository_version=/pulp/api/v3/repositories/python/python/6f6d94b0-9906-4b34-ba90-2973ccb767d9/versions/2/"
      }
    }
  }
}

(There are 2 things present because I added a second version of the package to see if one had to have the remote already assigned to the repository when adding a new content unit for it to work)

I shall skip the response for the remote since it is long, but it has excludes: ["package"] and policy: "on_demand" as I expected.

Maybe there is some issue with the way I have created the remote, or something else?

By the way, there is a definite documentation bug regarding the policy - the description is inconsistent on possible values. There is a common issue throughout the auto-generated API documentation where only the types are included. Often it is not clear without already being fully familiar with the system and API what object a pulp_href refers to, since all objects have hrefs. In this specific case, the meaning of the different policies is not explained beyond the names of the enum, but there are many others.

Reproduce the package installation with the shown pip command, then run the listed pulp python remote and repository commands and inspect the remote and repository version responses. Start by checking how the configured remote, excludes, and on_demand policy affect dependency retrieval. Done means the dependency behavior is explained or corrected, with the policy documentation and API descriptions made consistent if that is part of the fix.