Skip to content

Commit

Permalink
cleans up docstrings
Browse files Browse the repository at this point in the history
  • Loading branch information
@beaufour
beaufour committed Sep 9, 2023
1 parent c5130f3 commit 2049acf
Show file tree
Hide file tree
Showing 3 changed files with 76 additions and 75 deletions.
50 changes: 25 additions & 25 deletions flickr_download/filename_handlers.py
View file
Original file line number Diff line number Diff line change
Expand Up @@ -16,19 +16,19 @@
def _get_short_docstring(docstring: Optional[str]) -> Optional[str]:
"""Given a docstring return the first sentence of it.
@param: docstring: str, the docstring to parse
@return: str, the short docstring
:param: docstring: the docstring to parse
:returns: the short docstring
"""
return docstring.split(".")[0].strip() if docstring else None


def title(pset: Optional[Photoset], photo: Photo, suffix: Optional[str]) -> str:
"""Name file after title (falls back to photo id).
@param pset: the photoset
@param photo: the photo
@param suffix: optional suffix
@return: the filename
:param pset: the photoset
:param photo: the photo
:param suffix: optional suffix
:returns: the filename
"""
if not photo.title:
return idd(pset, photo, suffix)
Expand All @@ -39,21 +39,21 @@ def title(pset: Optional[Photoset], photo: Photo, suffix: Optional[str]) -> str:
def idd(_: Optional[Photoset], photo: Photo, suffix: Optional[str]) -> str:
"""Name file after photo id.
@param pset: the photoset
@param photo: the photo
@param suffix: optional suffix
@return: the filename
:param pset: the photoset
:param photo: the photo
:param suffix: optional suffix
:returns: the filename
"""
return f"{photo.id}{suffix}"


def title_and_id(pset: Optional[Photoset], photo: Photo, suffix: Optional[str]) -> str:
"""Name file after title and photo id.
@param pset: Flickr.Photoset, the photoset
@param photo: Flickr.Photo, the photo
@param suffix: str, optional suffix
@return: str, the filename
:param pset: the photoset
:param photo: the photo
:param suffix: optional suffix
:returns: the filename
"""
if not photo.title:
return idd(pset, photo, suffix)
Expand All @@ -64,10 +64,10 @@ def title_and_id(pset: Optional[Photoset], photo: Photo, suffix: Optional[str])
def id_and_title(pset: Optional[Photoset], photo: Photo, suffix: Optional[str]) -> str:
"""Name file after photo id and title.
@param pset: Flickr.Photoset, the photoset
@param photo: Flickr.Photo, the photo
@param suffix: str, optional suffix
@return: str, the filename
:param pset: the photoset
:param photo: the photo
:param suffix: optional suffix
:returns: the filename
"""
if not photo.title:
return idd(pset, photo, suffix)
Expand All @@ -83,10 +83,10 @@ def title_increment(pset: Optional[Photoset], photo: Photo, suffix: Optional[str
"""Name file after photo title, but add an incrementing counter on
duplicates.
@param pset: Flickr.Photoset, the photoset
@param photo: Flickr.Photo, the photo
@param suffix: str, optional suffix
@return: str, the filename
:param pset: the photoset
:param photo: the photo
:param suffix: optional suffix
:returns: the filename
"""
if not photo.title:
return idd(pset, photo, suffix)
Expand All @@ -112,16 +112,16 @@ def title_increment(pset: Optional[Photoset], photo: Photo, suffix: Optional[str
def get_filename_handler(name: str) -> FilenameHandler:
"""Returns the given filename handler as a function.
@param name: str, name of the handler to return
@return: Function, handler
:param name: name of the handler to return
:returns: handler
"""
return HANDLERS[name or DEFAULT_HANDLER]


def get_filename_handler_help() -> str:
"""Returns a description of each handler to be used for help output.
@return: str, help text
:returns: help text
"""
ret = []
HANDLERS.items()
Expand Down
83 changes: 42 additions & 41 deletions flickr_download/flick_download.py
View file
Original file line number Diff line number Diff line change
Expand Up @@ -49,11 +49,11 @@
def _init(key: str, secret: str, oauth: bool) -> bool:
"""Initialize API.
@see: http://www.flickr.com/services/api/
:see: http://www.flickr.com/services/api/
@param key: API key
@param secret: API secret
@param oauth: do user authentication (via OAuth)
:param key: API key
:param secret: API secret
:param oauth: do user authentication (via OAuth)
"""
Flickr.set_keys(key, secret)
if not oauth:
Expand Down Expand Up @@ -82,7 +82,7 @@ def _init(key: str, secret: str, oauth: bool) -> bool:
def _load_defaults() -> Dict[str, Any]:
"""Load default parameters from config file.
@return: default parameters
:returns: default parameters
"""
filename = os.path.expanduser(CONFIG_FILE)
logging.debug("Loading configuration from %s", filename)
Expand Down Expand Up @@ -119,11 +119,11 @@ def download_set(
) -> None:
"""Download the set with 'set_id' to the current directory.
@param set_id: id of the photo set
@param get_filename: function that creates a filename for the photo
@param size_label: size to download (or None for largest available)
@param skip_download: do not actually download the photo
@param save_json: save photo info as .json file
:param set_id: id of the photo set
:param get_filename: function that creates a filename for the photo
:param size_label: size to download (or None for largest available)
:param skip_download: do not actually download the photo
:param save_json: save photo info as .json file
"""
pset = Flickr.Photoset(id=set_id)
download_list(
Expand All @@ -142,12 +142,12 @@ def download_list(
) -> None:
"""Download all the photos in the given photo list.
@param pset: photo list to download
@param photos_title: name of the photo list
@param get_filename: function that creates a filename for the photo
@param size_label: size to download (or None for largest available)
@param skip_download: do not actually download the photo
@param save_json: save photo info as .json file
:param pset: photo list to download
:param photos_title: name of the photo list
:param get_filename: function that creates a filename for the photo
:param size_label: size to download (or None for largest available)
:param skip_download: do not actually download the photo
:param save_json: save photo info as .json file
"""

photos = Walker(pset.getPhotos)
Expand Down Expand Up @@ -204,15 +204,16 @@ def do_download_photo(
) -> None:
"""Handle the downloading of a single photo.
@param dirname: directory to download to
@param pset: photo list to download
@param photo: photo to download
@param size_label: size to download (or None for largest available)
@param suffix: optional suffix to add to file name
@param get_filename: function that creates a filename for the photo
@param skip_download: do not actually download the photo
@param save_json: save photo info as .json file
@param metadata_db: optional metadata database to record downloads in
:param dirname: directory to download to
:param pset: photo list to download
:param photo: photo to download
:param size_label: size to download (or None for largest available)
:param suffix: optional suffix to add to file name
:param get_filename: function that creates a filename for the photo
:param skip_download: do not actually download the photo
:param save_json: save photo info as .json file
:param metadata_db: optional metadata database to record downloads
in
"""
if metadata_db:
if metadata_db.execute(
Expand Down Expand Up @@ -300,11 +301,11 @@ def download_photo(
) -> None:
"""Download one photo.
@param photo_id: id of the photo
@param get_filename: function that creates a filename for the photo
@param size_label: size to download (or None for largest available)
@param skip_download: do not actually download the photo
@param save_json: save photo info as .json file
:param photo_id: id of the photo
:param get_filename: function that creates a filename for the photo
:param size_label: size to download (or None for largest available)
:param skip_download: do not actually download the photo
:param save_json: save photo info as .json file
"""
photo = Flickr.Photo(id=photo_id)
suffix = f" ({size_label})" if size_label else ""
Expand Down Expand Up @@ -336,11 +337,11 @@ def download_user(
) -> None:
"""Download all the sets owned by the given user.
@param username: username
@param get_filename: function that creates a filename for the photo
@param size_label: size to download (or None for largest available)
@param skip_download: do not actually download the photo
@param save_json: save photo info as .json file
:param username: username
:param get_filename: function that creates a filename for the photo
:param size_label: size to download (or None for largest available)
:param skip_download: do not actually download the photo
:param save_json: save photo info as .json file
"""
user = find_user(username)
photosets = Walker(user.getPhotosets) # pylint: disable=E1101
Expand All @@ -360,11 +361,11 @@ def download_user_photos(
) -> None:
"""Download all the photos owned by the given user.
@param username: username
@param get_filename: function that creates a filename for the photo
@param size_label: size to download (or None for largest available)
@param skip_download: do not actually download the photo
@param save_json: save photo info as .json file
:param username: username
:param get_filename: function that creates a filename for the photo
:param size_label: size to download (or None for largest available)
:param skip_download: do not actually download the photo
:param save_json: save photo info as .json file
"""
user = find_user(username)
download_list(
Expand All @@ -375,7 +376,7 @@ def download_user_photos(
def print_sets(username: str) -> None:
"""Print all sets for the given user.
@param username: the name of the user
:param username: the name of the user
"""
user = find_user(username)
photosets = Walker(user.getPhotosets) # pylint: disable=E1101
Expand Down
18 changes: 9 additions & 9 deletions flickr_download/utils.py
View file
Original file line number Diff line number Diff line change
Expand Up @@ -81,8 +81,8 @@ def serialize_json(obj: Any) -> Any:
def replace_path_sep(name: str) -> str:
"""Replaces the path separator(s) with an underscore.
@param name: file or dir name
@return: new name
:param name: file or dir name
:returns: new name
"""
ret = name.replace(os.path.sep, "_")
if os.path.altsep:
Expand All @@ -94,27 +94,27 @@ def replace_path_sep(name: str) -> str:
def get_filename(photo: str) -> str:
"""Get a file name for a photo.
@param photoset: name of photo
@return: file name
:param photoset: name of photo
:returns: file name
"""
return str(sanitize_filename(replace_path_sep(photo)))


def get_dirname(photoset: str) -> str:
"""Get a directory name for a photo set.
@param photoset: name of photoset
@return: directory / path name
:param photoset: name of photoset
:returns: directory / path name
"""
return str(sanitize_filepath(replace_path_sep(photoset)))


def get_full_path(pset: str, photo: str) -> str:
"""Assemble a full path from the photoset and photo titles.
@param pset: photo set name
@param photo: photo name
@return: full sanitized path
:param pset: photo set name
:param photo: photo name
:returns: full sanitized path
"""
return os.path.join(get_dirname(pset), get_filename(photo))

Expand Down

0 comments on commit 2049acf

Please sign in to comment.