diff --git a/.gitignore b/.gitignore index 47657f4..be12549 100644 --- a/.gitignore +++ b/.gitignore @@ -70,7 +70,7 @@ instance/ # Sphinx documentation docs/_build/ -docs/man +docs/man/.doctrees # PyBuilder .pybuilder/ diff --git a/CHANGELOG.md b/CHANGELOG.md index 0f68127..eb9732d 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,5 +1,30 @@ # Changelog +## 3.3.0 (06/29/2023) + +## Breaking + +* Drop support for EOL versions Python 3.6 and Python 3.7. + +### Bugfixes + +* Return `str` instead of `list` when executing `tldr -l` (thanks [@uunnxx](https://github.com/uunnxx)) +* Use pathlib instead of os.path (thanks [@vitorhcl](https://github.com/vitorhcl)) +* Respect language settings when geting a list of commands (thanks [@frenzymadness](https://github.com/frenzymadness)) +* Fix `--search` option (thanks [@CleanMachine1](https://github.com/CleanMachine1)) + +### Features + +* Add support for BSD platform directories (thanks [@vitorhcl](https://github.com/vitorhcl)) +* Add `--update` long option (thanks [@owenvoke](https://github.com/owenvoke)) +* Add support for fetching individual translation archives for cache (thanks [@SaurabhDRao](https://github.com/SaurabhDRao)) +* Add support to show message for other versions of the same page in other platforms (thanks [@Jaimepas77](https://github.com/Jaimepas77)) +* Update `DOWNLOAD_CACHE_LOCATION` to use GitHub Releases (thanks [@vitorhcl](https://github.com/vitorhcl)) +* Add `macos` alias for `osx` directory and update `--platform` option (thanks [@patricedenis](https://github.com/patricedenis)) +* Add support for escaping placeholders for special pages (thanks [@kbdharun](https://github.com/kbdharun)) +* Add support for Python 3.11 and Python 3.12 (thanks [@kbdharun](https://github.com/kbdharun)) +* Add support for [Client Specification v2.2](https://github.com/tldr-pages/tldr/releases/tag/v2.2) + ## 3.2.0 (05/09/2023) ### Bugfixes diff --git a/LICENSE.md b/LICENSE.md index 0f1ceea..39851b4 100644 --- a/LICENSE.md +++ b/LICENSE.md @@ -1,6 +1,6 @@ The MIT License (MIT) -Copyright (c) 2014 Felix Yan +Copyright (c) 2014 Felix Yan and 2014-present tldr-pages contributors Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal diff --git a/README.md b/README.md index 184643e..546e45a 100644 --- a/README.md +++ b/README.md @@ -2,10 +2,11 @@ [![PyPI Release](https://img.shields.io/pypi/v/tldr.svg)](https://pypi.python.org/pypi/tldr) [![Build](https://github.com/tldr-pages/tldr-python-client/workflows/Test/badge.svg?branch=main)](https://github.com/tldr-pages/tldr-python-client/actions?query=branch%3Amain) +[![Snap Release](https://snapcraft.io/tldr/badge.svg)](https://snapcraft.io/tldr) Python command-line client for [tldr pages](https://github.com/tldr-pages/tldr). -![tldr pages example](https://raw.github.com/tldr-pages/tldr/main/images/tldr-dark.png) +![Tldr Python client displaying the tar page](https://raw.github.com/tldr-pages/tldr-python-client/main/images/tldr-dark.png) ## Installation @@ -42,7 +43,7 @@ sudo snap install tldr ## Usage -``` +```txt usage: tldr command [options] Python command line client for tldr @@ -57,7 +58,7 @@ options: -u, --update, --update_cache Update the local cache of pages and exit -p PLATFORM, --platform PLATFORM - Override the operating system [linux, osx, sunos, windows, common] + Override the operating system [android, freebsd, linux, netbsd, openbsd, osx, sunos, windows, common] -l, --list List all available commands for operating system -s SOURCE, --source SOURCE Override the default page source @@ -92,13 +93,14 @@ export TLDR_DOWNLOAD_CACHE_LOCATION="https://tldr-pages.github.io/assets/tldr.zi Cache is downloaded from `TLDR_DOWNLOAD_CACHE_LOCATION` (defaults to the one described in [the client specification](https://github.com/tldr-pages/tldr/blob/main/CLIENT-SPECIFICATION.md#caching)), unzipped and extracted into the [local cache directory](#cache-location). Pages are loaded directly from `TLDR_PAGES_SOURCE_LOCATION` if `tldr ` is used. - `TLDR_CACHE_ENABLED` (default is `1`): - - If set to `1`, the client will first try to load from cache, and fall back to fetching from the internet if the cache doesn't exist or is too old. - - If set to `0`, the client will fetch from the internet, and fall back to the cache if the page cannot be fetched from the internet. + - If set to `1`, the client will first try to load from cache, and fall back to fetching from the internet if the cache doesn't exist or is too old. + - If set to `0`, the client will fetch from the internet, and fall back to the cache if the page cannot be fetched from the internet. - `TLDR_CACHE_MAX_AGE` (default is `168` hours, which is equivalent to a week): maximum age of the cache in hours to be considered as valid when `TLDR_CACHE_ENABLED` is set to `1`. #### Cache location In order of precedence: + - `$XDG_CACHE_HOME/tldr` - `$HOME/.cache/tldr` - `~/.cache/tldr` @@ -130,7 +132,7 @@ an autocomplete for `tldr` for `fish`. For networks that sit behind a proxy, it may be necessary to disable SSL verification for the client to function. Setting the following: -- `TLDR_ALLOW_INSECURE=1` +- `TLDR_ALLOW_INSECURE=1` will disable SSL certificate inspection. This __should be avoided__ unless absolutely necessary. diff --git a/docs/conf.py b/docs/conf.py index b1d8ba5..b962e41 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -17,8 +17,8 @@ # -- Project information ----------------------------------------------------- project = 'tldr' -copyright = '2014, Felix Yan' -author = 'Felix Yan' +copyright = '2014, Felix Yan and 2014-present, tldr-pages contributors' +author = 'Felix Yan and tldr-pages contributors' from tldr import __version__ # noqa: E402 release = __version__ diff --git a/docs/man/tldr.1 b/docs/man/tldr.1 new file mode 100644 index 0000000..6750041 --- /dev/null +++ b/docs/man/tldr.1 @@ -0,0 +1,105 @@ +.\" Man page generated from reStructuredText. +. +. +.nr rst2man-indent-level 0 +. +.de1 rstReportMargin +\\$1 \\n[an-margin] +level \\n[rst2man-indent-level] +level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] +- +\\n[rst2man-indent0] +\\n[rst2man-indent1] +\\n[rst2man-indent2] +.. +.de1 INDENT +.\" .rstReportMargin pre: +. RS \\$1 +. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin] +. nr rst2man-indent-level +1 +.\" .rstReportMargin post: +.. +.de UNINDENT +. RE +.\" indent \\n[an-margin] +.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]] +.nr rst2man-indent-level -1 +.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] +.in \\n[rst2man-indent\\n[rst2man-indent-level]]u +.. +.TH "TLDR" "1" "Jun 29, 2024" "" "tldr" +.SH NAME +tldr \- tldr 3.3.0 +.sp +Python command line client for tldr + +.INDENT 0.0 +.INDENT 3.5 +.sp +.EX +usage: tldr command [options] +.EE +.UNINDENT +.UNINDENT +.SH POSITIONAL ARGUMENTS +.INDENT 0.0 +.TP +.B command +command to lookup +.UNINDENT +.SH NAMED ARGUMENTS +.INDENT 0.0 +.TP +.B \-v, \-\-version +show program\(aqs version number and exit +.TP +.B \-\-search +Search for a specific command from a query +.TP +.B \-u, \-\-update, \-\-update_cache +Update the local cache of pages and exit +.sp +Default: False +.TP +.B \-p, \-\-platform +Possible choices: android, freebsd, linux, netbsd, openbsd, osx, sunos, windows, common +.sp +Override the operating system [android, freebsd, linux, netbsd, openbsd, osx, sunos, windows, common] +.TP +.B \-l, \-\-list +List all available commands for operating system +.sp +Default: False +.TP +.B \-s, \-\-source +Override the default page source +.sp +Default: \(dq\X'tty: link https://raw.githubusercontent.com/tldr-pages/tldr/main/pages'\fI\%https://raw.githubusercontent.com/tldr\-pages/tldr/main/pages\fP\X'tty: link'\(dq +.TP +.B \-c, \-\-color +Override color stripping +.TP +.B \-r, \-\-render +Render local markdown files +.sp +Default: False +.TP +.B \-L, \-\-language +Override the default language +.TP +.B \-m, \-\-markdown +Just print the plain page file. +.sp +Default: False +.TP +.B \-\-print\-completion +Possible choices: bash, zsh, tcsh +.sp +print shell completion script +.UNINDENT +.SH AUTHOR +Felix Yan and tldr-pages contributors +.SH COPYRIGHT +2014, Felix Yan and 2014-present, tldr-pages contributors +.\" Generated by docutils manpage writer. +. diff --git a/images/tldr-dark.png b/images/tldr-dark.png new file mode 100644 index 0000000..4886297 Binary files /dev/null and b/images/tldr-dark.png differ diff --git a/setup.py b/setup.py index a31a2da..1da313b 100644 --- a/setup.py +++ b/setup.py @@ -16,8 +16,7 @@ setup( name='tldr', - author='Felix Yan', - author_email='felixonmars@gmail.com', + author='Felix Yan and tldr-pages contributors', url='https://github.com/tldr-pages/tldr-python-client', description='command line client for tldr', long_description=Path(setup_dir, 'README.md').open().read(), @@ -45,12 +44,16 @@ "Natural Language :: English", "Operating System :: POSIX :: Linux", "Operating System :: POSIX :: SunOS/Solaris", + "Operating System :: POSIX :: BSD :: FreeBSD", + "Operating System :: POSIX :: BSD :: NetBSD", + "Operating System :: POSIX :: BSD :: OpenBSD", "Operating System :: MacOS :: MacOS X", "Operating System :: Microsoft :: Windows", "Programming Language :: Python :: 3.8", "Programming Language :: Python :: 3.9", "Programming Language :: Python :: 3.10", "Programming Language :: Python :: 3.11", + "Programming Language :: Python :: 3.12", "Topic :: Utilities", "Topic :: System" ] diff --git a/snap/snapcraft.yaml b/snap/snapcraft.yaml index bdd8cde..b42df5d 100644 --- a/snap/snapcraft.yaml +++ b/snap/snapcraft.yaml @@ -1,22 +1,20 @@ -name: tldr # you probably want to 'snapcraft register ' -base: core22 # the base snap is the execution environment for this snap -version: '3.2.0' # just for humans, typically '1.2+git' or '1.3.2' -summary: tldr python client # 79 char long summary +name: tldr +base: core24 +version: '3.2.0' +summary: tldr python client description: Python command-line client for tldr pages. -grade: stable # must be 'stable' to release into candidate/stable channels -confinement: strict # use 'strict' once you have the right plugs and slots +grade: stable +confinement: strict parts: tldr: - # See 'snapcraft plugins' plugin: python source: https://github.com/tldr-pages/tldr-python-client.git source-tag: $SNAPCRAFT_PROJECT_VERSION build-environment: - # WORKAROUND: The python plugin is broken with gnome extension - PATH: ${CRAFT_PART_INSTALL}/bin:${PATH} - - PYTHONPATH: ${CRAFT_PART_INSTALL}/lib/python3.10/site-packages + - PYTHONPATH: ${CRAFT_PART_INSTALL}/lib/python3.12/site-packages override-pull: | craftctl default sed -i "/data_files=\[('share\/man\/man1', \['docs\/man\/tldr\.1'\])\],/d" setup.py @@ -37,14 +35,14 @@ parts: - -bin/Activate.ps1 - -bin/python - -bin/python3 - - -bin/python3.10 + - -bin/python3.12 - -lib/*/*/sphinx* - -lib/*/*/setuptools* - -lib/*/*/pip* - -lib/*/*/pkg_resources - -bin/pip - -bin/pip3 - - -bin/pip3.10 + - -bin/pip3.12 - -bin/[a-s, u-z, _]* - -pyvenv.cfg - -lib/*/*/[a-b, d-r, u-z, A-B, D-R, U-Z, _]* @@ -56,8 +54,7 @@ apps: tldr: command: bin/tldr environment: - PYTHONPATH: $SNAP/lib/python3.10/site-packages:$PYTHONPATH - #LD_LIBRARY_PATH: $SNAP/lib/man-db:$SNAP/lib:$SNAP/lib/$CRAFT_ARCH_TRIPLET + PYTHONPATH: $SNAP/lib/python3.12/site-packages:$PYTHONPATH plugs: - network - home diff --git a/tldr.py b/tldr.py index 88000e6..02bcaf5 100755 --- a/tldr.py +++ b/tldr.py @@ -18,8 +18,8 @@ import colorama # Required for Windows import shtab -__version__ = "3.2.0" -__client_specification__ = "1.5" +__version__ = "3.3.0" +__client_specification__ = "2.2" REQUEST_HEADERS = {'User-Agent': 'tldr-python-client'} PAGES_SOURCE_LOCATION = os.environ.get( @@ -433,24 +433,35 @@ def output(page: str, plain: bool = False) -> None: colored( line.replace('>', '').replace('<', ''), *colors_of('description') - ) + ) sys.stdout.buffer.write(line.encode('utf-8')) elif line[0] == '-': line = '\n' + ' ' * LEADING_SPACES_NUM + \ colored(line, *colors_of('example')) sys.stdout.buffer.write(line.encode('utf-8')) elif line[0] == '`': - line = line[1:-1] # need to actually parse `` + line = line[1:-1] # Remove backticks for parsing + + # Handle escaped placeholders first + line = line.replace(r'\{\{', '__ESCAPED_OPEN__') + line = line.replace(r'\}\}', '__ESCAPED_CLOSE__') + elements = [' ' * 2 * LEADING_SPACES_NUM] for item in COMMAND_SPLIT_REGEX.split(line): item, replaced = PARAM_REGEX.subn( - lambda x: colored( - x.group('param'), *colors_of('parameter')), + lambda x: colored(x.group('param'), *colors_of('parameter')), item) if not replaced: item = colored(item, *colors_of('command')) elements.append(item) - sys.stdout.buffer.write(''.join(elements).encode('utf-8')) + + line = ''.join(elements) + + # Restore escaped placeholders + line = line.replace('__ESCAPED_OPEN__', '{{') + line = line.replace('__ESCAPED_CLOSE__', '}}') + + sys.stdout.buffer.write(line.encode('utf-8')) print() print()