PR#2281: more generic docs for Client initialization - copr/copr

copr / copr

#2281 more generic docs for Client initialization

Merged 2 years ago by praiskup. Opened 2 years ago by praiskup.

Unknown source docs-python into main

python: fix docs warning

Pavel Raiskup • 2 years ago

17f7fd1

python: more generic docs for Client initialization

Pavel Raiskup • 2 years ago

b5939cc

python/docs/client_v3/client_initialization.rst

file modified

+37 -7

		`@@ -1,11 +1,41 @@`
		`Client initialization`
		`=====================`

		`- Before an API client can be used, it needs to be initialized with a configuration. There are several ways to do it.`
		- The most standard option is reading the ``~/.config/copr`` file and providing it to the ``Client`` class. Please read
		`- https://copr.fedorainfracloud.org/api/ for more information about API token.`
		`+ Before an API client can be used, it needs to be initialized with a`
		`+ configuration. There are several ways to do it. The most standard option is`
		+ reading the ``~/.config/copr`` file and providing it to the ``Client`` class.

		`- ::`
		`+ Such a configuration file typically has::`
		`+`
		`+ [copr-cli]`
		`+ copr_url = https://copr.fedorainfracloud.org`
		`+ username = coprusername`
		`+ login = secretlogin`
		`+ token = secrettoken`
		`+ # expiration date: 2023-01-17`
		`+`
		`+ To get your configuration file for the Fedora Copr instance, go to`
		`+ https://copr.fedorainfracloud.org/api/`
		`+`
		+ The only mandatory field though is ``copr_url``::
		`+`
		`+ [copr-cli]`
		`+ copr_url = https://copr.fedorainfracloud.org`
		`+`
		`+ With such a simplified configuration, you can still do the read-only API`
		`+ queries that do not require user-authentication (listing projects, builds,`
		`+ etc.).`
		`+`
		`+ Alternatively, the Copr server you work with might support GSSAPI`
		+ authentication (Fedora Copr does). To let the Client use your ``kinit``
		`+ tokens, you need to enable GSSAPI authentication first::`
		`+`
		`+ [copr-cli]`
		`+ copr_url = https://copr.fedorainfracloud.org`
		`+ gssapi = true`
		`+`
		`+ Having the config file prepared, you can finally use it for creating a`
		+ ``Client`` instance. Just like::

		`from copr.v3 import Client`
		`from pprint import pprint`
		`@@ -17,7 +47,7 @@`
		`{'copr_url': u'https://copr.fedorainfracloud.org',`
		`'login': u'secretlogin',`
		`'token': u'secrettoken',`
		`- 'username': u'frostyx'}`
		`+ 'username': u'coprusername'}`

		A different config file can be easily used by passing its path to ``create_from_config_file`` method.

		`@@ -34,7 +64,7 @@`
		`config = {'copr_url': u'https://copr.fedorainfracloud.org',`
		`'login': u'secretlogin',`
		`'token': u'secrettoken',`
		`- 'username': u'frostyx'}`
		`+ 'username': u'coprusername'}`

		`client = Client(config)`
		`assert client.config == config`
		`@@ -53,7 +83,7 @@`
		`config = {'copr_url': u'https://copr.fedorainfracloud.org',`
		`'login': u'secretlogin',`
		`'token': u'secrettoken',`
		`- 'username': u'frostyx'}`
		`+ 'username': u'coprusername'}`

		`build_proxy = BuildProxy(config)`

python/docs/conf.py

file modified

+1 -1

		`@@ -136,7 +136,7 @@`
		`# Add any paths that contain custom static files (such as style sheets) here,`
		`# relative to this directory. They are copied after the builtin static files,`
		`# so a file named "default.css" will overwrite the builtin "default.css".`
		`- html_static_path = ['_static']`
		`+ #html_static_path = ['_static']`

		`# If not '', a 'Last updated on:' timestamp is inserted at every page bottom,`
		`# using the given strftime format.`

praiskup commented 2 years ago

Mention that copr_url= is the only mandatory field in the configuration,
and that there's the gssapi= token. Use a placeholder copr_url and
username in the examples.

Reported to me by several folks around the LEAPP team, because they
needed access to the read-only part of the API from a publicly available
CI workers.

zuul commented 2 years ago

Build succeeded.

csdiff-pylint : SUCCESS in 52s

mbocek commented 2 years ago

👍

frostyx commented 2 years ago

@praiskup, I like all the changes, thank you.
But are you sure we want to replace the actual Copr URL with a placeholder? The majority of people are using Fedora Copr instance, nobody cares about devel and users of internal Copr will figure out that they need to replace the URL. We can even explicitly state it here in the docs, that users of different instances need to change the URL appropriately.

I think using the actual Copr URL in the docs would be clearer.

praiskup commented 2 years ago

But are you sure we want to replace the actual Copr URL with a placeholder?

That was my intention (long-term I'd like to have the documentation instance-agnostic, especially seeing the increased user demand for running their own Copr instances).

praiskup commented on line 23 of python/docs/client_v3/client_initialization.rst 2 years ago

bug

praiskup commented 2 years ago

Updated, PTAL

rebased onto d5ce647afcb9d0c2ea4871e73bf32ee0936eb2c4

2 years ago

zuul commented 2 years ago

Build succeeded.