From: claromes Date: Sun, 25 May 2025 18:24:50 +0000 (-0300) Subject: update docs X-Git-Url: https://git.claromes.com/?a=commitdiff_plain;h=9adace5f7fd196e7eb0986135cddecf0c7f8cdad;p=waybacktweets.git update docs --- diff --git a/README.md b/README.md index a895035..20265b3 100644 --- a/README.md +++ b/README.md @@ -6,19 +6,23 @@ Retrieves archived tweets CDX data from the Wayback Machine, performs necessary ## Installation +Python 3.10+ is required to install `waybacktweets`. + ```shell -pip install waybacktweets +pipx install waybacktweets ``` +[Read more about the installation options](https://waybacktweets.claromes.com/installation). + ## CLI ```shell -Usage: waybacktweets [OPTIONS] USERNAME - +Usage: + waybacktweets [OPTIONS] USERNAME USERNAME: The Twitter username without @ Options: - -c, --collapse [urlkey|digest|timestamp:XX] + -c, --collapse [urlkey|digest|timestamp:xx] Collapse results based on a field, or a substring of a field. XX in the timestamp value ranges from 1 to 14, comparing the @@ -39,16 +43,13 @@ Options: -v, --verbose Shows the log. --version Show the version and exit. -h, --help Show this message and exit. - - Examples: - - Retrieve all tweets: waybacktweets jack - - With options and verbose output: waybacktweets --from 20200305 --to 20231231 --limit 300 --verbose jack - - Documentation: - - https://waybacktweets.claromes.com/ +Examples: + waybacktweets jack + waybacktweets --from 20200305 --to 20231231 --limit 300 --verbose jack +Repository: + https://github.com/claromes/waybacktweets +Documentation: + https://waybacktweets.claromes.com ``` ## Module diff --git a/docs/cli.rst b/docs/cli.rst index 2a16040..be6872e 100644 --- a/docs/cli.rst +++ b/docs/cli.rst @@ -8,6 +8,15 @@ Usage :prog: waybacktweets :nested: full +Examples +--------- + +``waybacktweets jack`` + +``waybacktweets --from 20200305 --to 20231231 --limit 300 --verbose jack`` + +``waybacktweets -f 20200305 -t 20231231 -l 300 -v jack`` + Collapsing ------------ diff --git a/docs/installation.rst b/docs/installation.rst index 9c942b1..d151344 100644 --- a/docs/installation.rst +++ b/docs/installation.rst @@ -3,12 +3,19 @@ Installation **It is compatible with Python versions 3.10 and above.** +Using pipx +------------ + + .. code-block:: shell + + pipx install waybacktweets + Using pip ------------ .. code-block:: shell - pip install waybacktweets + pip3 install waybacktweets Using Poetry ------------ @@ -38,7 +45,7 @@ From source .. code-block:: shell - pip install poetry + pip3 install poetry **Install the dependencies:** @@ -56,7 +63,7 @@ From source .. code-block:: shell - poetry run waybacktweets [SUBCOMMANDS] + poetry run waybacktweets [OPTIONS] USERNAME **Run the Streamlit App:** @@ -81,5 +88,3 @@ From source .. code-block:: shell make clean html - -`Read the Poetry CLI documentation `_. diff --git a/pyproject.toml b/pyproject.toml index 5311355..ddbf334 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -7,14 +7,13 @@ license = "GPLv3" readme = "README.md" repository = "https://github.com/claromes/waybacktweets" keywords = [ - "twitter", + "Twitter", "X", "tweet", - "internet-archive", - "wayback-machine", - "osint-tools", - "osint", - "command-line", + "Internet Archive", + "Wayback Machine", + "OSINT", + "SOCMINT", ] classifiers = [ "Development Status :: 5 - Production/Stable", @@ -28,7 +27,7 @@ classifiers = [ "Topic :: Software Development", "Topic :: Utilities", ] -exclude = ["app/**", "assets/**", "docs/**", ".streamlit/**"] +exclude = ["app/**", "legacy_app/**", ".streamlit/**", "assets/**", "docs/**", "build/**", ".github/**", ".git/**", ".gitignore", ".pre-commit-config.yaml", "CITATION.cff"] [tool.poetry.urls] "Homepage" = "https://waybacktweets.claromes.com/" @@ -64,7 +63,7 @@ profile = "black" [tool.flake8] max-line-length = 88 -extend-ignore = ["E203", "E701"] +extend-ignore = ["E203", "E701", "E501"] [tool.poetry.scripts] waybacktweets = 'waybacktweets._cli:main' diff --git a/waybacktweets/_cli.py b/waybacktweets/_cli.py index 7b2c747..9499f10 100644 --- a/waybacktweets/_cli.py +++ b/waybacktweets/_cli.py @@ -17,6 +17,40 @@ from waybacktweets.config.config import config PACKAGE_NAME = "waybacktweets" +class CustomCommand(click.Command): + """ + Custom Click command that overrides the default help message. + """ + + def format_help( + self, ctx: click.Context, formatter: click.HelpFormatter + ) -> None: # noqa: E501 + """ + Customize the help message shown when the command is invoked with --help. + + Args: + ctx (click.Context): The Click context for the command. + formatter (click.HelpFormatter): The formatter used to generate the help text. + """ # noqa: E501 + formatter.write_heading("Usage") + formatter.write_text(f" {PACKAGE_NAME} [OPTIONS] USERNAME") + formatter.write_text(" USERNAME: The Twitter username without @") + + self.format_options(ctx, formatter) + + formatter.write_heading("Examples") + formatter.write_text(" waybacktweets jack") + formatter.write_text( + " waybacktweets --from 20200305 --to 20231231 --limit 300 --verbose jack" + ) + + formatter.write_heading("Repository") + formatter.write_text(" https://github.com/claromes/waybacktweets") + + formatter.write_heading("Documentation") + formatter.write_text(" https://waybacktweets.claromes.com") + + def _parse_date( ctx: Optional[Any] = None, param: Optional[Any] = None, value: Optional[str] = None ) -> Optional[str]: @@ -30,7 +64,7 @@ def _parse_date( Returns: The input date string formatted in the "YYYYMMDD" format, or None if no date string was provided. - """ # noqa: E501 + """ try: if value is None: return None @@ -43,15 +77,7 @@ def _parse_date( @click.command( - context_settings={"help_option_names": ["-h", "--help"]}, - epilog=""" -Examples:\n - Retrieve all tweets: waybacktweets jack\n\n - With options and verbose output: waybacktweets --from 20200305 --to 20231231 --limit 300 --verbose jack\n\n - -Documentation:\n - https://waybacktweets.claromes.com/ - """, # noqa: E501 + cls=CustomCommand, context_settings={"help_option_names": ["-h", "--help"]}, help="" ) @click.argument("username", type=str) @click.option( @@ -123,8 +149,20 @@ def main( verbose: Optional[bool], ) -> None: """ - USERNAME: The Twitter username without @ - """ + Handles CLI queries for archived tweets with filtering and pagination. + + Args: + username (str): Twitter username to search (without the @ symbol). + collapse (Optional[str]): Collapse results based on a specific field or a substring + of a field. Possible values include 'urlkey', 'digest', or 'timestamp:XX', where + XX is the number of digits to match in timestamps (recommended: 4 or more). + timestamp_from (Optional[str]): Start date for filtering results (format: YYYYMMDD). + timestamp_to (Optional[str]): End date for filtering results (format: YYYYMMDD). + limit (Optional[int]): Maximum number of results to return. + resumption_key (Optional[str]): Resume a previous query using this key (for pagination). + matchtype (Optional[str]): Filter by URL match type: 'exact', 'prefix', 'host', or 'domain'. + verbose (Optional[bool]): Print verbose logs during execution. + """ # noqa: E501 try: config.verbose = verbose