Merge branch 'main' into main

Author: kbdharun

.github/dependabot.yml

@@ -3,4 +3,4 @@ updates:
   - package-ecosystem: "github-actions"
     directory: "/"
     schedule:
-      interval: "monthly"
+      interval: "weekly"

.github/workflows/publish.yml

@@ -1,5 +1,6 @@
-# This workflow will upload a Python Package using Twine when a release is created
+# This workflow will upload a Python Package using Trusted Publishers automatically when a release is created
 # For more information see: https://help.github.com/en/actions/language-and-framework-guides/using-python-with-github-actions#publishing-to-package-registries
+# and https://docs.pypi.org/trusted-publishers/using-a-publisher/.
 
 name: Upload Python Package
 
@@ -8,14 +9,22 @@ on:
     types: [created]
 
 jobs:
-  deploy:
-
+  pypi-publish:
     runs-on: ubuntu-latest
+
+    environment: 
+      name: pypi
+      url: https://pypi.org/project/tldr/
+
+    permissions:
+      contents: read
+      id-token: write # Required for accessing OpenID Connect (OIDC) token for PyPI trusted publisher
+
     steps:
-    - uses: actions/checkout@v4
+    - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
 
     - name: Set up Python
-      uses: actions/setup-python@v5
+      uses: actions/setup-python@8d9ed9ac5c53483de85588cdf95a591a75ab9f55 # v5.5.0
       with:
         python-version: '3.8'
 
@@ -56,7 +65,4 @@ jobs:
         .
 
     - name: Publish package
-      uses: pypa/gh-action-pypi-publish@release/v1
-      with:
-        user: __token__
-        password: ${{ secrets.PYPI_PASSWORD }}
+      uses: pypa/gh-action-pypi-publish@76f52bc884231f62b9a034ebfe128415bbaabdfc # v1.12.4

.github/workflows/test.yml

@@ -4,17 +4,18 @@ on: ['push', 'pull_request']
 
 jobs:
   build:
-    runs-on: ubuntu-latest
+    runs-on: ${{ matrix.os }}
 
     strategy:
       matrix:
+        os: ['ubuntu-latest', 'ubuntu-24.04-arm']
         python-version: ['3.8', '3.9', '3.10', '3.11', '3.12', 'pypy3.9', 'pypy3.10']
 
     steps:
-    - uses: actions/checkout@v4
+    - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
 
     - name: Set up Python ${{ matrix.python-version }}
-      uses: actions/setup-python@v5
+      uses: actions/setup-python@8d9ed9ac5c53483de85588cdf95a591a75ab9f55 # v5.5.0
       with:
         python-version: ${{ matrix.python-version }}
 
@@ -25,15 +26,15 @@ jobs:
 
     - name: Install sphinx dependencies
       run: >-
-        python -m
+        python3 -m
         pip install
         sphinx
         sphinx-argparse
         --user
 
     - name: Install tldr dependencies
       run: >-
-        python -m
+        python3 -m
         pip install
         -r
         requirements.txt
@@ -47,23 +48,30 @@ jobs:
       run: python3 -m flake8
 
     - name: Run test suite
-      run: python3 setup.py pytest
+      run: python3 -m pytest tests/
 
     - name: Test tldr cli
       run: |
         python3 -m pip install .
         tldr --version
 
   build-snap:
-    runs-on: ubuntu-latest
+    runs-on: ${{ matrix.os }}
+    needs: ['build']
+
+    strategy:
+      matrix:
+        os: ['ubuntu-latest', 'ubuntu-24.04-arm']
 
     steps:
      - uses: actions/checkout@v4
-     - uses: snapcore/action-build@v1
+
+     - uses: canonical/action-build@3bdaa03e1ba6bf59a65f84a751d943d549a54e79 # v1.3.0
        id: snapcraft-build
        with:
          snapcraft-args: "-v"
-     - uses: actions/upload-artifact@v4
+
+     - uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4.6.2
        with:
          name: ${{ steps.snapcraft-build.outputs.snap }}
          path: ${{ steps.snapcraft-build.outputs.snap }}

.gitignore

@@ -70,7 +70,7 @@ instance/
 
 # Sphinx documentation
 docs/_build/
-docs/man
+docs/man/.doctrees
 
 # PyBuilder
 .pybuilder/

CHANGELOG.md

@@ -1,5 +1,30 @@
 # Changelog
 
+## 3.3.0 (06/29/2024)
+
+## 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

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

README.md

@@ -2,14 +2,20 @@
 
 [![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
 
-[![Packaging status](https://repology.org/badge/vertical-allrepos/tldr-python-client.svg)](https://repology.org/project/python-tldr-client/versions)
+<details open>
+  <summary>Check Repology Packaging Status!</summary>
+  <a href="https://repology.org/project/tldr-python-client/versions">
+      <img src="https://repology.org/badge/vertical-allrepos/tldr-python-client.svg" alt="Packaging status">
+  </a>
+</details>
 
 ### from PyPI
 
@@ -37,28 +43,32 @@ sudo snap install tldr
 
 ## Usage
 
-```
-usage: tldr [-u] [-p PLATFORM] [-s SOURCE] [-c] [-r] [-L LANGUAGE] command
+```txt
+usage: tldr command [options]
 
 Python command line client for tldr
 
 positional arguments:
   command               command to lookup
 
-optional arguments:
+options:
   -h, --help            show this help message and exit
   -v, --version         show program's version number and exit
-  -u, --update_cache    Update the local cache of pages and exit
+  --search "KEYWORDS"   Search for a specific command from a query
+  -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
   -c, --color           Override color stripping
   -r, --render          Render local markdown files
-  -l, --list            List all available commands for operating system    
   -L LANGUAGE, --language LANGUAGE
                         Override the default language
+  -m, --markdown        Just print the plain page file.
+  --print-completion {bash,zsh,tcsh}
+                        print shell completion script
 ```
 
 ## Configuration
@@ -75,24 +85,26 @@ export TLDR_LANGUAGE="es"
 export TLDR_CACHE_ENABLED=1
 export TLDR_CACHE_MAX_AGE=720
 export TLDR_PAGES_SOURCE_LOCATION="https://raw.githubusercontent.com/tldr-pages/tldr/main/pages"
-export TLDR_DOWNLOAD_CACHE_LOCATION="https://tldr-pages.github.io/assets/tldr.zip"
+export TLDR_DOWNLOAD_CACHE_LOCATION="https://github.com/tldr-pages/tldr/releases/latest/download/tldr.zip"
+export TLDR_OPTIONS=short
 ```
 
 ### Cache
 
 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 <command>` 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.
-* `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`.
+- `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.
+- `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`
+
+- `$XDG_CACHE_HOME/tldr`
+- `$HOME/.cache/tldr`
+- `~/.cache/tldr`
 
 If you are experiencing issues with *tldr*, consider deleting the cache files before trying other measures.
 
@@ -121,7 +133,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.
 
@@ -132,30 +144,34 @@ It is possible to use a different certificate store/bundle by setting:
 ### Colors
 
 Values of the `TLDR_COLOR_x` variables may consist of three parts:
-* Font color: `blue, green, yellow, cyan, magenta, white, grey, red`
-* Background color: `on_blue, on_cyan, on_magenta, on_white, on_grey, on_yellow, on_red, on_green`
-* Additional effects, which depends on platform: `reverse, blink, dark, concealed, underline, bold`
+
+- Font color: `blue, green, yellow, cyan, magenta, white, grey, red`
+- Background color: `on_blue, on_cyan, on_magenta, on_white, on_grey, on_yellow, on_red, on_green`
+- Additional effects, which depend on the platform: `reverse, blink, dark, concealed, underline, bold`
 
 You may specify as many additional effects as you want, while only one of font and background color.
 
-Any of the values of above may be omitted. For example, you can do similar things as the following:
-* `TLDR_COLOR_NAME=""` use default system font color with default background color without any effects
-* `TLDR_COLOR_DESCRIPTION="white"` for white text on default system background color without any effects
-* `TLDR_COLOR_NAME="cyan dark"` for dark cyan text on default system background color
-* `TLDR_COLOR_NAME="on_red"` for default system font color on red background color
-* `TLDR_COLOR_PARAMETER="red on_yellow underline"` for underlined red text on yellow background
-* `TLDR_COLOR_NAME="bold underline"` for default system font and background colors with underline and bolded effects
+Any of the values above may be omitted. For example, you can do similar things as the following:
+
+- `TLDR_COLOR_NAME=""` use default system font color with default background color without any effects
+- `TLDR_COLOR_DESCRIPTION="white"` for white text on default system background color without any effects
+- `TLDR_COLOR_NAME="cyan dark"` for dark cyan text on default system background color
+- `TLDR_COLOR_NAME="on_red"` for default system font color on the red background color
+- `TLDR_COLOR_PARAMETER="red on_yellow underline"` for underlined red text on yellow background
+- `TLDR_COLOR_NAME="bold underline"` for default system font and background colors with underline and bolded effects
 
 ### Language
 
-The language that tldr will use is dependent on a number of factors. If you specify a language via the
+The language that tldr will use is dependent on several factors. If you specify a language via the
 `--language` flag, tldr will attempt to use that language and only that language. Otherwise, it will
 try to use the language specified by `TLDR_LANGUAGE`. If it is not set, or the page does not exist in that language,
 then tldr will use the
 language set using `LANGUAGE` and `LANG` (ignoring the values `C` and `POSIX`).
-If neither are set, then tldr will always attempt to get the `en` page. Finally, if `LANG` is set, it uses `LANGUAGE`, if set,
-first as the priority list to try languages in, followed by `LANG` if not included in `LANGUAGE`
-and `en` as fallback (assuming it does not already appear somewhere in `LANGUAGE` or `LANG`).
+
+If neither is set, then tldr will always attempt to get the `en` page. Finally, if `LANG` is set, it uses `LANGUAGE`, if set,
+first, as the priority list to try languages in, followed by `LANG` if not included in `LANGUAGE`
+and `en` as a fallback (assuming it does not already appear somewhere in `LANGUAGE` or `LANG`).
+
 All language values should be set to a value that follows [RFC 1766](https://tools.ietf.org/html/rfc1766.html),
 with the special exceptions of `C` and `POSIX` which are ignored.
 
@@ -164,8 +180,12 @@ with the special exceptions of `C` and `POSIX` which are ignored.
 If you wish to use your own instance of the tldr pages instead of the default repository, you
 can either use the `--source` flag when using tldr or by specifying the following environment variables:
 
-* `TLDR_PAGES_SOURCE_LOCATION` to control where to get individual pages from
-  * defaults to `https://raw.githubusercontent.com/tldr-pages/tldr/main/pages`
-  * it can also point to local directory using `file:///path/to/directory`
-* `TLDR_DOWNLOAD_CACHE_LOCATION` to control where to pull a zip of all pages from
-  * defaults to `https://tldr-pages.github.io/assets/tldr.zip`
+- `TLDR_PAGES_SOURCE_LOCATION` to control where to get individual pages from.
+  - defaults to `https://raw.githubusercontent.com/tldr-pages/tldr/main/pages`.
+  - it can also point to a local directory using `file:///path/to/directory`.
+- `TLDR_DOWNLOAD_CACHE_LOCATION` to control where to pull a zip of all pages from.
+  - defaults to `https://github.com/tldr-pages/tldr/releases/latest/download/tldr.zip`.
+
+### Command options
+
+Pages might contain `{{[*|*]}}` patterns to let the client decide whether to show shortform or longform versions of options. This can be configured with `TLDR_OPTIONS`, which accepts values `short`, `long` and `both`

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__