Adding simple developer docs with example client

[vsoch]

This PR aims to fix two issues that I just opened:

• Add developer python example to generate custom manifest/config #30 : a common use case is "I want to push these blobs with these custom media types) and since the current client is built around anticipating that we would eventually have different kinds of remotes/providers (right now there is just one) it probably needs to stay that way until we decide we aren't going to do this. However, using *args and **kwargs makes the interactions confusing at best. So for the being I think it's important we provide a simpler "these are my blobs and media types just push them!" example. This PR will add developer (Python API) docs that show how to do exactly this, over-riding the default push function.
• Bug: when layer media_type provided, not actually set #31 since we always constrain an upload to be a single layer media type or compressed, we totally missed the third case of a custom media type, which I implemented in the example above. So this PR fixes that bug.

Signed-off-by: vsoch vsoch@users.noreply.github.com

[vsoch]

Going to test out my client before this is ready for review, will report back / update as needed.

[vsoch]

oooh nice found another bug!

  File "/usr/lib/python3/dist-packages/requests/utils.py", line 944, in check_header_validity
    raise InvalidHeader("Value for header {%s: %s} must be of type str or "
requests.exceptions.InvalidHeader: Value for header {Content-Length: 0} must be of type str or bytes, not <class 'int'>

[vsoch]

okay for my tester, it looks like the push isn't working with basic auth, I'm going to reproduce the request with my action and see if I can figure out why.

Generated 2 build artifacts for python builder.
application/vnd.oci.image.layer.v1.tar+gzip        /tmp/pakages-tmp.4aoeutb1/pakages-0.0.16.tar.gz
application/vnd.cyclonedx                          /tmp/pakages-tmp.4aoeutb1/sbom.json
authentication required
Found username and password for basic auth
Issue with https://ghcr.io/v2/syspack/pakages/pakages-bundle/blobs/upload/d043cbf1-d14a-441e-bc86-a8a8a771051d:
Unauthorized
Error: Process completed with exit code 1.

[vsoch]

okay I think I see the problem but I'm not sure how to fix it:

Generated 2 build artifacts for python builder.
application/vnd.oci.image.layer.v1.tar+gzip        /tmp/pakages-tmp.nzm5oadu/pakages-0.0.16.tar.gz
application/vnd.cyclonedx                          /tmp/pakages-tmp.nzm5oadu/sbom.json
authentication required
Found username and password for basic auth
Issue with https://ghcr.io/v2/syspack/pakages/pakages-bundle/blobs/upload/dc8bd1a5-b013-45bd-8844-b65acf97092a:
STATUS CODE 401
Unauthorized
authHeader: ***"https://ghcr.io/token",service="ghcr.io",scope="repository:syspack/pakages/pakages-bundle:pull"
realm https://ghcr.io/token
200
OK
dict_keys(['token'])
STATUS CODE 401
authHeader: ***"https://ghcr.io/token",service="ghcr.io",scope="repository:syspack/pakages/pakages-bundle:pull"
realm https://ghcr.io/token
403
Forbidden

I tried setting "scope" as a param to be the same as the above (but with push appended) and it didn't change the outcome.

Update this is fixed! I had one line commented out that I forgot to uncomment that would update the PATCH request to include the token header.

[sabre1041]

Where are archives originating from?

[vsoch]

Ah good question! It's just a lookup with filenames and then media types, and I didn't properly put it in the code but poorly showed it here: https://github.com/oras-project/oras-py/pull/32/files#diff-2f73f28403e770eba62d042f1e50ad0a240eb39585108e48497be198ca59f090R69-R70

I'll update this to explicitly have that named archives, and added to the example.

[vsoch]

okay clarified here! 72afc46

[sabre1041]

LGTM

[vsoch]

Thank you @sabre1041 ! And especially given your travel and being busy!

@sajayantony this is another one we will need your blessing on. Since one merge will warrant needing to update the second PR, my preference is to merge this one first, then I'll rebase #28 to make sure the fixes here still work.