DocuShare

class docushare.DocuShare(base_url)

Bases: object

This class represents a session to access a DocuShare site.

An instance of this class stores login session so that the user does not have to enter the authentication information many times. It also caches some metadata so that it does not have to access the DocuShare multiple times to get the same information.

Parameters: base_url (str) – Base URL of DocuShare. Both ‘http’ and ‘https’ schemes are supported. For example, https://your.docushare.domain/docushare/.

Warning

This class is not thread-safe. Use an appropriate mechanism if you want to use an instance of this class in multiple threads.

Attributes Summary

`cookies`	Cookies of the current session.
`is_logged_in`	indicates if this instance successfully logged in the DocuShare site.
`logger`	Logger of this instance
`username`	Currently logged in DocuShare username, or None if login has not been done yet.

Methods Summary

`close`()	Close the session with the DocuShare site.
`download`(hdl, path[, size_for_progress_report])	Download the given handle (Document or Version) as a file.
`http_get`(url)	Access the given URL with HTTP GET method using the current DocuShare session.
`http_post`(url[, data])	Access the given URL with HTTP POST method using the current DocuShare session.
`login`([username, password, retry_count, domain])	Login the DocuShare site.
`object`(hdl)	Get an instance that represents a DocuShare object.
`url`([resource, hdl])

Attributes Documentation

cookies

Cookies of the current session.

See more details in requests.Session.cookies.

is_logged_in

indicates if this instance successfully logged in the DocuShare site.

Type: bool

logger

Logger of this instance

It may be useful to change logging settings like log level.

Examples

>>> import logging
>>> ds = DocuShare(base_url='https://your.domain/docushare/')
>>> ds.logger.setLevel(logging.DEBUG)

Type: logging.Logger

username

Currently logged in DocuShare username, or None if login has not been done yet.

Type: str or None

Methods Documentation

close()

Close the session with the DocuShare site.

You need to run login() again to access any resources on the DocuShare site again.

download(hdl, path, size_for_progress_report=1000000)

Download the given handle (Document or Version) as a file.

Parameters

hdl (Handle or str) – DocuShare handle to download as a file or a string that represents a valid DocuShare handle.
path (path-like object) – Destination file path.
size_for_progress_report (int) – This method shows a progress bar using tqdm <https://tqdm.github.io/> if the file size is more than the specified size in bytes.

Raises

DocuShareNotFoundError – If the given handle does not exist.
DocuShareNotAuthorizedError – If the user is not authorized to access the URL.

http_get(url)

Access the given URL with HTTP GET method using the current DocuShare session.

This method may be useful to access the resource that PyDocuShare does not directly support (e.g. Wiki, Calendar).

Parameters

url (str) – URL to access.

Returns

HTTP response.

Return type

requests.Response

Raises

requests.HTTPError – If HTTP error status code was returned.
DocuShareSystemError – If the DocuShare site encounters a system error.
DocuShareNotAuthorizedError – If the user is not authorized to access the URL.
DocuShareParseError – If this method fails to parse the DocuShare system error page.

http_post(url, data=None)

Access the given URL with HTTP POST method using the current DocuShare session.

This method may be useful to access the resource that PyDocuShare does not directly support (e.g. uploading documents).

Parameters

url (str) – URL to access.
data – See requests.Session.post() for more details.

Returns

HTTP response.

Return type

requests.Response

Raises

requests.HTTPError – If HTTP error status code was returned.

login(username=None, password=PasswordOption.ASK, retry_count=3, domain='DocuShare')

Login the DocuShare site.

This must be executed, at least, once before accessing any other resources in DocuShare.

Parameters

username (str or None) – Username for Docushare. Specify None to prompt the user to enter the username.
password (str or PasswordOption) – Password for the DocuShare user. If a string is given, it is considered as the password and this method never prompts the user. If an PasswordOption enum is given, this method behaves as described in each enum value.
retry_count (int) – The user will have a chance to enter the credentials this amount of time.
domain (str) – Domain to specify when logging in DocuShare. Typically, it is ‘DocuShare’.

Raises

DocuShareParseError – If this method fails to parse the DocuShare login page.

object(hdl)

Get an instance that represents a DocuShare object.

Parameters

hdl (Handle or str) – DocuShare handle for which you want to get an instance that represents a DocuShare object. It can be a string that represents a DocuShare handle like “Document-xxxxx”.

Returns

An instance through which you can get individual property values, file, etc.

Return type

DocuShareBaseObject

Raises

DocuShareNotFoundError – If the given handle does not exist.
DocuShareNotAuthorizedError – If the user is not authorized to access the URL.
DocuShareParseError – If this method fails to parse one of DocuShare pages related to the given handle.

url(resource=None, hdl=None)