Commitf555bfb

authored and

committed

docs(api): document usage of head() methods

1 parentce9216c commitf555bfbCopy full SHA for f555bfb

File tree

+32

-1

lines changed

+32

-1

lines changed

Lines changed: 22 additions & 0 deletions

Original file line number	Diff line number	Diff line change
`@@ -238,6 +238,28 @@ a project (the previous example used 2 API calls):`
`238`	`238`	`project= gl.projects.get(1,lazy=True)# no API call`
`239`	`239`	`project.star()# API call`
`240`	`240`
	`241`	+``head()`` methods
	`242`	`+========================`
	`243`	`+`
	`244`	+All endpoints that support ``get()`` and ``list()`` also support a ``head()`` method.
	`245`	`+In this case, the server responds only with headers and not the response JSON or body.`
	`246`	`+This allows more efficient API calls, such as checking repository file size without`
	`247`	`+fetching its content.`
	`248`	`+`
	`249`	`+..note::`
	`250`	`+`
	`251`	+ In some cases, GitLab may omit specific headers. See more in the:ref:`pagination` section.
	`252`	`+`
	`253`	`+..code-block::python`
	`254`	`+`
	`255`	`+# See total number of personal access tokens for current user`
	`256`	`+ gl.personal_access_tokens.head()`
	`257`	`+print(headers["X-Total"])`
	`258`	`+`
	`259`	`+# See returned content-type for project GET endpoint`
	`260`	`+ headers= gl.projects.head("gitlab-org/gitlab")`
	`261`	`+print(headers["Content-Type"])`
	`262`	`+`
`241`	`263`	`.. _pagination:`
`242`	`264`
`243`	`265`	`Pagination`

Lines changed: 10 additions & 1 deletion

Original file line number	Diff line number	Diff line change
`@@ -380,7 +380,16 @@ Get a file::`
`380`	`380`
`381`	`381`	`# get the decoded content`
`382`	`382`	`print(f.decode())`
`383`		`-`
	`383`	`+`
	`384`	`+Get file details from headers, without fetching its entire content::`
	`385`	`+`
	`386`	`+ headers = project.files.head('README.rst', ref='main')`
	`387`	`+`
	`388`	`+ # Get the file size:`
	`389`	`+ # For a full list of headers returned, see upstream documentation.`
	`390`	`+ # https://docs.gitlab.com/ee/api/repository_files.html#get-file-from-repository`
	`391`	`+ print(headers["X-Gitlab-Size"])`
	`392`	`+`
`384`	`393`	`Get a raw file::`
`385`	`394`
`386`	`395`	`raw_content = project.files.raw(file_path='README.rst', ref='main')`

Comments

(0)