From 9f68c6521c3b6d1e6d56092989eccdf92f681e4b Mon Sep 17 00:00:00 2001 From: narugo1992 Date: Mon, 25 Dec 2023 16:38:58 +0800 Subject: [PATCH] dev(narugo): add more docs --- docs/source/api_doc/entry/base.rst | 53 ++++++++++++++++++++++++ docs/source/api_doc/entry/cli.rst | 14 +++++++ docs/source/api_doc/entry/dispatch.rst | 22 ++++++++++ docs/source/api_doc/entry/download.rst | 15 +++++++ docs/source/api_doc/entry/index.rst | 17 ++++++++ docs/source/api_doc/entry/upload.rst | 15 +++++++ docs/source/index.rst | 1 + hfutils/entry/base.py | 57 +++++++++++++++++++++++++- hfutils/entry/download.py | 36 ++++++++++++++-- hfutils/entry/upload.py | 41 ++++++++++++++++-- 10 files changed, 263 insertions(+), 8 deletions(-) create mode 100644 docs/source/api_doc/entry/base.rst create mode 100644 docs/source/api_doc/entry/cli.rst create mode 100644 docs/source/api_doc/entry/dispatch.rst create mode 100644 docs/source/api_doc/entry/download.rst create mode 100644 docs/source/api_doc/entry/index.rst create mode 100644 docs/source/api_doc/entry/upload.rst diff --git a/docs/source/api_doc/entry/base.rst b/docs/source/api_doc/entry/base.rst new file mode 100644 index 0000000000..b888a1d7e4 --- /dev/null +++ b/docs/source/api_doc/entry/base.rst @@ -0,0 +1,53 @@ +hfutils.entry.base +================================ + +.. currentmodule:: hfutils.entry.base + +.. automodule:: hfutils.entry.base + + +CONTEXT_SETTINGS +-------------------------- + +.. autodata:: CONTEXT_SETTINGS + + + +ClickWarningException +-------------------------------- + +.. autoclass:: ClickWarningException + :members: exit_code, show + + + +ClickErrorException +------------------------------------ + +.. autoclass:: ClickErrorException + :members: exit_code, show + + + +print_exception +---------------------------------- + +.. autofunction:: print_exception + + + +KeyboardInterrupted +------------------------------------ + +.. autoclass:: KeyboardInterrupted + :members: __init__, exit_code, show + + + +command_wrap +------------------------------- + +.. autofunction:: command_wrap + + + diff --git a/docs/source/api_doc/entry/cli.rst b/docs/source/api_doc/entry/cli.rst new file mode 100644 index 0000000000..474e114379 --- /dev/null +++ b/docs/source/api_doc/entry/cli.rst @@ -0,0 +1,14 @@ +hfutils.entry.cli +================================ + +.. currentmodule:: hfutils.entry.cli + +.. automodule:: hfutils.entry.cli + + +cli +---------------------- + +.. autodata:: cli + + diff --git a/docs/source/api_doc/entry/dispatch.rst b/docs/source/api_doc/entry/dispatch.rst new file mode 100644 index 0000000000..91e0bccd79 --- /dev/null +++ b/docs/source/api_doc/entry/dispatch.rst @@ -0,0 +1,22 @@ +hfutils.entry.dispatch +================================ + +.. currentmodule:: hfutils.entry.dispatch + +.. automodule:: hfutils.entry.dispatch + + +print_version +---------------------------------------- + +.. autofunction:: print_version + + + +hfutilcli +---------------------------------------- + +.. autofunction:: hfutilcli + + + diff --git a/docs/source/api_doc/entry/download.rst b/docs/source/api_doc/entry/download.rst new file mode 100644 index 0000000000..112ece5e9b --- /dev/null +++ b/docs/source/api_doc/entry/download.rst @@ -0,0 +1,15 @@ +hfutils.entry.download +================================ + +.. currentmodule:: hfutils.entry.download + +.. automodule:: hfutils.entry.download + + +NoRemotePathAssignedWithDownload +-------------------------------------------- + +.. autoclass:: NoRemotePathAssignedWithDownload + :members: exit_code, show + + diff --git a/docs/source/api_doc/entry/index.rst b/docs/source/api_doc/entry/index.rst new file mode 100644 index 0000000000..714ba58485 --- /dev/null +++ b/docs/source/api_doc/entry/index.rst @@ -0,0 +1,17 @@ +hfutils.entry +================================ + +.. currentmodule:: hfutils.entry + +.. automodule:: hfutils.entry + + +.. toctree:: + :maxdepth: 3 + + base + cli + dispatch + download + upload + diff --git a/docs/source/api_doc/entry/upload.rst b/docs/source/api_doc/entry/upload.rst new file mode 100644 index 0000000000..ab50a5f3ff --- /dev/null +++ b/docs/source/api_doc/entry/upload.rst @@ -0,0 +1,15 @@ +hfutils.entry.upload +================================ + +.. currentmodule:: hfutils.entry.upload + +.. automodule:: hfutils.entry.upload + + +NoRemotePathAssignedWithUpload +-------------------------------------- + +.. autoclass:: NoRemotePathAssignedWithUpload + :members: exit_code, show + + diff --git a/docs/source/index.rst b/docs/source/index.rst index e4ee948b04..2a3b44388c 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -30,6 +30,7 @@ configuration file's structure and their versions. api_doc/archive/index api_doc/config/index + api_doc/entry/index api_doc/operate/index api_doc/utils/index diff --git a/hfutils/entry/base.py b/hfutils/entry/base.py index 637bb20511..b69b2316b6 100644 --- a/hfutils/entry/base.py +++ b/hfutils/entry/base.py @@ -15,18 +15,50 @@ class ClickWarningException(ClickException): + """ + Custom exception class for displaying warnings in yellow color. + + :param message: The error message. + :type message: str + """ + def show(self, file: Optional[IO] = None) -> None: + """ + Display the warning message in yellow. + + :param file: File to write the output to. + :type file: Optional[IO] + """ click.secho(self.format_message(), fg='yellow', file=sys.stderr) class ClickErrorException(ClickException): + """ + Custom exception class for displaying errors in red color. + + :param message: The error message. + :type message: str + """ + def show(self, file: Optional[IO] = None) -> None: + """ + Display the error message in red. + + :param file: File to write the output to. + :type file: Optional[IO] + """ click.secho(self.format_message(), fg='red', file=sys.stderr) -# noinspection PyShadowingBuiltins def print_exception(err: BaseException, print: Optional[Callable] = None): - # noinspection PyShadowingBuiltins + """ + Print exception information, including traceback. + + :param err: The exception object. + :type err: BaseException + :param print: Custom print function. If not provided, uses built-in print. + :type print: Optional[Callable] + """ print = print or builtins.print lines = list(itertools.chain(*map( @@ -47,13 +79,34 @@ def print_exception(err: BaseException, print: Optional[Callable] = None): class KeyboardInterrupted(ClickWarningException): + """ + Exception class for handling keyboard interruptions. + + :param msg: Custom message to display. + :type msg: Optional[str] + """ exit_code = 0x7 def __init__(self, msg=None): + """ + Initialize the exception. + + :param msg: Custom message to display. + :type msg: Optional[str] + """ ClickWarningException.__init__(self, msg or 'Interrupted.') def command_wrap(): + """ + Decorator for wrapping Click commands. + + This decorator catches exceptions and provides consistent error handling. + + :return: Decorator function. + :rtype: Callable + """ + def _decorator(func): @wraps(func) def _new_func(*args, **kwargs): diff --git a/hfutils/entry/download.py b/hfutils/entry/download.py index f4c5cca7e8..085c13883b 100644 --- a/hfutils/entry/download.py +++ b/hfutils/entry/download.py @@ -8,11 +8,23 @@ from ..operate.base import REPO_TYPES, RepoTypeTyping -class NoRemotePathAssigned(ClickErrorException): +class NoRemotePathAssignedWithDownload(ClickErrorException): + """ + Custom exception class for indicating that no remote path in the repository is assigned. + """ exit_code = 0x11 def _add_download_subcommand(cli: click.Group) -> click.Group: + """ + Add the 'download' subcommand to the CLI. + + :param cli: The Click CLI application. + :type cli: click.Group + :return: The modified Click CLI application. + :rtype: click.Group + """ + @cli.command('download', help='Download data from HuggingFace.\n\n' 'Set environment $HF_TOKEN to use your own access token.', context_settings=CONTEXT_SETTINGS) @@ -34,9 +46,27 @@ def _add_download_subcommand(cli: click.Group) -> click.Group: def download(repo_id: str, repo_type: RepoTypeTyping, file_in_repo: Optional[str], archive_in_repo: Optional[str], dir_in_repo: Optional[str], output_path: str, revision: str): + """ + Download data from HuggingFace repositories. + + :param repo_id: Repository to download from. + :type repo_id: str + :param repo_type: Type of the HuggingFace repository. + :type repo_type: RepoTypeTyping + :param file_in_repo: File in repository to download. + :type file_in_repo: Optional[str] + :param archive_in_repo: Archive file in repository to download and extract from. + :type archive_in_repo: Optional[str] + :param dir_in_repo: Directory in repository to download the full directory tree. + :type dir_in_repo: Optional[str] + :param output_path: Output path for download. + :type output_path: str + :param revision: Revision of repository. + :type revision: str + """ if not file_in_repo and not archive_in_repo and not dir_in_repo: - raise NoRemotePathAssigned('No remote path in repository assigned.\n' - 'One of the -f, -a or -d option is required.') + raise NoRemotePathAssignedWithDownload('No remote path in repository assigned.\n' + 'One of the -f, -a, or -d option is required.') if file_in_repo: if archive_in_repo: diff --git a/hfutils/entry/upload.py b/hfutils/entry/upload.py index 6f1712955f..6b0370f431 100644 --- a/hfutils/entry/upload.py +++ b/hfutils/entry/upload.py @@ -8,11 +8,23 @@ from ..operate.base import REPO_TYPES, RepoTypeTyping, get_hf_client -class NoRemotePathAssigned(ClickErrorException): +class NoRemotePathAssignedWithUpload(ClickErrorException): + """ + Custom exception class for indicating that no remote path in the repository is assigned. + """ exit_code = 0x21 def _add_upload_subcommand(cli: click.Group) -> click.Group: + """ + Add the 'upload' subcommand to the CLI. + + :param cli: The Click CLI application. + :type cli: click.Group + :return: The modified Click CLI application. + :rtype: click.Group + """ + @cli.command('upload', help='Upload data from HuggingFace.\n\n' 'Set environment $HF_TOKEN to use your own access token.', context_settings=CONTEXT_SETTINGS) @@ -39,9 +51,32 @@ def _add_upload_subcommand(cli: click.Group) -> click.Group: def upload(repo_id: str, repo_type: RepoTypeTyping, file_in_repo: Optional[str], archive_in_repo: Optional[str], dir_in_repo: Optional[str], input_path: str, revision: str, clear: bool, private: bool): + """ + Upload data to HuggingFace repositories. + + :param repo_id: Repository to upload to. + :type repo_id: str + :param repo_type: Type of the HuggingFace repository. + :type repo_type: RepoTypeTyping + :param file_in_repo: File in repository to upload. + :type file_in_repo: Optional[str] + :param archive_in_repo: Archive file in repository to upload and extract from. + :type archive_in_repo: Optional[str] + :param dir_in_repo: Directory in repository to upload the full directory tree. + :type dir_in_repo: Optional[str] + :param input_path: Input path for upload. + :type input_path: str + :param revision: Revision of repository. + :type revision: str + :param clear: Clear the remote directory before uploading. + Only applied when -d is used. + :type clear: bool + :param private: Use private repository when created. + :type private: bool + """ if not file_in_repo and not archive_in_repo and not dir_in_repo: - raise NoRemotePathAssigned('No remote path in repository assigned.\n' - 'One of the -f, -a or -d option is required.') + raise NoRemotePathAssignedWithUpload('No remote path in repository assigned.\n' + 'One of the -f, -a, or -d option is required.') hf_client = get_hf_client() if not hf_client.repo_exists(repo_id, repo_type=repo_type):