Skip to content

Clarify optional None parameters in docstrings #351

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 1 commit into
base: master
Choose a base branch
from
Open

Clarify optional None parameters in docstrings #351

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
30 changes: 15 additions & 15 deletions diskcache/core.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -420,7 +420,7 @@ class Cache:
def __init__(self, directory=None, timeout=60, disk=Disk, **settings):
"""Initialize cache instance.

:param str directory: cache directory
:param str or None directory: cache directory
:param float timeout: SQLite connection timeout
:param disk: Disk type or subclass for serialization
:param settings: any of DEFAULT_SETTINGS
Expand Down Expand Up @@ -757,10 +757,10 @@ def set(self, key, value, expire=None, read=False, tag=None, retry=False):

:param key: key for item
:param value: value for item
:param float expire: seconds until item expires
:param float or None expire: seconds until item expires
(default None, no expiry)
:param bool read: read value as bytes from file (default False)
:param str tag: text to associate with key (default None)
:param str or None tag: text to associate with key (default None)
:param bool retry: retry if database timeout occurs (default False)
:return: True if item was set
:raises Timeout: if database timeout occurs
Expand Down Expand Up @@ -931,7 +931,7 @@ def touch(self, key, expire=None, retry=False):
`False` (default).

:param key: key for item
:param float expire: seconds until item expires
:param float or None expire: seconds until item expires
(default None, no expiry)
:param bool retry: retry if database timeout occurs (default False)
:return: True if key was touched
Expand Down Expand Up @@ -977,10 +977,10 @@ def add(self, key, value, expire=None, read=False, tag=None, retry=False):

:param key: key for item
:param value: value for item
:param float expire: seconds until the key expires
:param float or None expire: seconds until the key expires
(default None, no expiry)
:param bool read: read value as bytes from file (default False)
:param str tag: text to associate with key (default None)
:param str or None tag: text to associate with key (default None)
:param bool retry: retry if database timeout occurs (default False)
:return: True if item was added
:raises Timeout: if database timeout occurs
Expand Down Expand Up @@ -1425,12 +1425,12 @@ def push(
'userids-500000000000000'

:param value: value for item
:param str prefix: key prefix (default None, key is integer)
:param str or None prefix: key prefix (default None, key is integer)
:param str side: either 'back' or 'front' (default 'back')
:param float expire: seconds until the key expires
:param float or None expire: seconds until the key expires
(default None, no expiry)
:param bool read: read value as bytes from file (default False)
:param str tag: text to associate with key (default None)
:param str or None tag: text to associate with key (default None)
:param bool retry: retry if database timeout occurs (default False)
:return: key for item in cache
:raises Timeout: if database timeout occurs
Expand Down Expand Up @@ -1533,7 +1533,7 @@ def pull(
>>> value
1234

:param str prefix: key prefix (default None, key is integer)
:param str or None prefix: key prefix (default None, key is integer)
:param default: value to return if key is missing
(default (None, None))
:param str side: either 'front' or 'back' (default 'front')
Expand Down Expand Up @@ -1648,7 +1648,7 @@ def peek(
>>> value
'c'

:param str prefix: key prefix (default None, key is integer)
:param str or None prefix: key prefix (default None, key is integer)
:param default: value to return if key is missing
(default (None, None))
:param str side: either 'front' or 'back' (default 'front')
Expand Down Expand Up @@ -1848,11 +1848,11 @@ def memoize(
TypeError: name cannot be callable

:param cache: cache to store callable arguments and return values
:param str name: name given for callable (default None, automatic)
:param str or None name: name given for callable (default None, automatic)
:param bool typed: cache different types separately (default False)
:param float expire: seconds until arguments expire
:param float or None expire: seconds until arguments expire
(default None, no expiry)
:param str tag: text to associate with arguments (default None)
:param str or None tag: text to associate with arguments (default None)
:param set ignore: positional or keyword args to ignore (default ())
:return: callable decorator

Expand Down Expand Up @@ -2084,7 +2084,7 @@ def expire(self, now=None, retry=False):
Raises :exc:`Timeout` error when database timeout occurs and `retry` is
`False` (default).

:param float now: current time (default None, ``time.time()`` used)
:param float or None now: current time (default None, ``time.time()`` used)
:param bool retry: retry if database timeout occurs (default False)
:return: count of items removed
:raises Timeout: if database timeout occurs
Expand Down
36 changes: 18 additions & 18 deletions diskcache/djangocache.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -48,7 +48,7 @@ def deque(self, name, maxlen=None):
"""Return Deque with given `name` in subdirectory.

:param str name: subdirectory name for Deque
:param maxlen: max length (default None, no max)
:param int or None maxlen: max length (default None, no max)
:return: Deque with given name

"""
Expand Down Expand Up @@ -83,9 +83,9 @@ def add(
:param value: value for item
:param float timeout: seconds until the item expires
(default 300 seconds)
:param int version: key version number (default None, cache parameter)
:param int or None version: key version number (default None, cache parameter)
:param bool read: read value as bytes from file (default False)
:param str tag: text to associate with key (default None)
:param str or None tag: text to associate with key (default None)
:param bool retry: retry if database timeout occurs (default True)
:return: True if item was added

Expand All @@ -110,7 +110,7 @@ def get(

:param key: key for item
:param default: return value if key is missing (default None)
:param int version: key version number (default None, cache parameter)
:param int or None version: key version number (default None, cache parameter)
:param bool read: if True, return file handle to value
(default False)
:param float expire_time: if True, return expire_time in tuple
Expand All @@ -128,7 +128,7 @@ def read(self, key, version=None):
"""Return file handle corresponding to `key` from Cache.

:param key: Python key to retrieve
:param int version: key version number (default None, cache parameter)
:param int or None version: key version number (default None, cache parameter)
:return: file open for reading in binary mode
:raises KeyError: if key is not found

Expand All @@ -153,9 +153,9 @@ def set(
:param value: value for item
:param float timeout: seconds until the item expires
(default 300 seconds)
:param int version: key version number (default None, cache parameter)
:param int or None version: key version number (default None, cache parameter)
:param bool read: read value as bytes from file (default False)
:param str tag: text to associate with key (default None)
:param str or None tag: text to associate with key (default None)
:param bool retry: retry if database timeout occurs (default True)
:return: True if item was set

Expand All @@ -172,7 +172,7 @@ def touch(self, key, timeout=DEFAULT_TIMEOUT, version=None, retry=True):
:param key: key for item
:param float timeout: seconds until the item expires
(default 300 seconds)
:param int version: key version number (default None, cache parameter)
:param int or None version: key version number (default None, cache parameter)
:param bool retry: retry if database timeout occurs (default True)
:return: True if key was touched

Expand All @@ -199,7 +199,7 @@ def pop(

:param key: key for item
:param default: return value if key is missing (default None)
:param int version: key version number (default None, cache parameter)
:param int or None version: key version number (default None, cache parameter)
:param float expire_time: if True, return expire_time in tuple
(default False)
:param tag: if True, return tag in tuple (default False)
Expand All @@ -214,7 +214,7 @@ def delete(self, key, version=None, retry=True):
"""Delete a key from the cache, failing silently.

:param key: key for item
:param int version: key version number (default None, cache parameter)
:param int or None version: key version number (default None, cache parameter)
:param bool retry: retry if database timeout occurs (default True)
:return: True if item was deleted

Expand All @@ -238,8 +238,8 @@ def incr(self, key, delta=1, version=None, default=None, retry=True):

:param key: key for item
:param int delta: amount to increment (default 1)
:param int version: key version number (default None, cache parameter)
:param int default: value if key is missing (default None)
:param int or None version: key version number (default None, cache parameter)
:param int or None default: value if key is missing (default None)
:param bool retry: retry if database timeout occurs (default True)
:return: new value for item on success else None
:raises ValueError: if key is not found and default is None
Expand Down Expand Up @@ -270,8 +270,8 @@ def decr(self, key, delta=1, version=None, default=None, retry=True):

:param key: key for item
:param int delta: amount to decrement (default 1)
:param int version: key version number (default None, cache parameter)
:param int default: value if key is missing (default None)
:param int or None version: key version number (default None, cache parameter)
:param int or None default: value if key is missing (default None)
:param bool retry: retry if database timeout occurs (default True)
:return: new value for item on success else None
:raises ValueError: if key is not found and default is None
Expand All @@ -284,7 +284,7 @@ def has_key(self, key, version=None):
"""Returns True if the key is in the cache and has not expired.

:param key: key for item
:param int version: key version number (default None, cache parameter)
:param int or None version: key version number (default None, cache parameter)
:return: True if key is found

"""
Expand Down Expand Up @@ -403,12 +403,12 @@ def memoize(
Remember to call memoize when decorating a callable. If you forget,
then a TypeError will occur.

:param str name: name given for callable (default None, automatic)
:param str or None name: name given for callable (default None, automatic)
:param float timeout: seconds until the item expires
(default 300 seconds)
:param int version: key version number (default None, cache parameter)
:param int or None version: key version number (default None, cache parameter)
:param bool typed: cache different types separately (default False)
:param str tag: text to associate with arguments (default None)
:param str or None tag: text to associate with arguments (default None)
:param set ignore: positional or keyword args to ignore (default ())
:return: callable decorator

Expand Down
16 changes: 8 additions & 8 deletions diskcache/fanout.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -21,7 +21,7 @@ def __init__(
):
"""Initialize cache instance.

:param str directory: cache directory
:param str or None directory: cache directory
:param int shards: number of shards to distribute writes
:param float timeout: SQLite connection timeout
:param disk: `Disk` instance for serialization
Expand Down Expand Up @@ -110,10 +110,10 @@ def set(self, key, value, expire=None, read=False, tag=None, retry=False):

:param key: key for item
:param value: value for item
:param float expire: seconds until the key expires
:param float or None expire: seconds until the key expires
(default None, no expiry)
:param bool read: read value as raw bytes from file (default False)
:param str tag: text to associate with key (default None)
:param str or None tag: text to associate with key (default None)
:param bool retry: retry if database timeout occurs (default False)
:return: True if item was set

Expand Down Expand Up @@ -145,7 +145,7 @@ def touch(self, key, expire=None, retry=False):
`True` (default `False`).

:param key: key for item
:param float expire: seconds until the key expires
:param float or None expire: seconds until the key expires
(default None, no expiry)
:param bool retry: retry if database timeout occurs (default False)
:return: True if key was touched
Expand Down Expand Up @@ -174,10 +174,10 @@ def add(self, key, value, expire=None, read=False, tag=None, retry=False):

:param key: key for item
:param value: value for item
:param float expire: seconds until the key expires
:param float or None expire: seconds until the key expires
(default None, no expiry)
:param bool read: read value as bytes from file (default False)
:param str tag: text to associate with key (default None)
:param str or None tag: text to associate with key (default None)
:param bool retry: retry if database timeout occurs (default False)
:return: True if item was added

Expand Down Expand Up @@ -592,7 +592,7 @@ def cache(self, name, timeout=60, disk=None, **settings):

:param str name: subdirectory name for Cache
:param float timeout: SQLite connection timeout
:param disk: Disk type or subclass for serialization
:param Disk or None disk: Disk type or subclass for serialization
:param settings: any of DEFAULT_SETTINGS
:return: Cache with given name

Expand Down Expand Up @@ -627,7 +627,7 @@ def deque(self, name, maxlen=None):
1

:param str name: subdirectory name for Deque
:param maxlen: max length (default None, no max)
:param int or None maxlen: max length (default None, no max)
:return: Deque with given name

"""
Expand Down
10 changes: 6 additions & 4 deletions diskcache/persistent.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -82,7 +82,8 @@ def __init__(self, iterable=(), directory=None, maxlen=None):
will *not* be automatically removed.

:param iterable: iterable of items to append to deque
:param directory: deque directory (default None)
:param str or None directory: deque directory (default None)
:param int or None maxlen: max length (default None, no max)

"""
self._cache = Cache(directory, eviction_policy='none')
Expand All @@ -106,6 +107,7 @@ def fromcache(cls, cache, iterable=(), maxlen=None):

:param Cache cache: cache to use
:param iterable: iterable of items
:param int or None maxlen: max length (default None, no max)
:return: initialized Deque

"""
Expand Down Expand Up @@ -953,7 +955,7 @@ def push(self, value, prefix=None, side='back'):
'fruit-500000000000000'

:param value: value for item
:param str prefix: key prefix (default None, key is integer)
:param str or None prefix: key prefix (default None, key is integer)
:param str side: either 'back' or 'front' (default 'back')
:return: key for item in cache

Expand Down Expand Up @@ -991,7 +993,7 @@ def pull(self, prefix=None, default=(None, None), side='front'):
>>> index.pull(prefix='fruit')
(None, None)

:param str prefix: key prefix (default None, key is integer)
:param str or None prefix: key prefix (default None, key is integer)
:param default: value to return if key is missing
(default (None, None))
:param str side: either 'front' or 'back' (default 'front')
Expand Down Expand Up @@ -1200,7 +1202,7 @@ def memoize(self, name=None, typed=False, ignore=()):
...
TypeError: name cannot be callable

:param str name: name given for callable (default None, automatic)
:param str or None name: name given for callable (default None, automatic)
:param bool typed: cache different types separately (default False)
:param set ignore: positional or keyword args to ignore (default ())
:return: callable decorator
Expand Down
4 changes: 2 additions & 2 deletions diskcache/recipes.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -407,9 +407,9 @@ def memoize_stampede(

:param cache: cache to store callable arguments and return values
:param float expire: seconds until arguments expire
:param str name: name given for callable (default None, automatic)
:param str or None name: name given for callable (default None, automatic)
:param bool typed: cache different types separately (default False)
:param str tag: text to associate with arguments (default None)
:param str or None tag: text to associate with arguments (default None)
:param set ignore: positional or keyword args to ignore (default ())
:return: callable decorator

Expand Down