Merge branch 'main' into feat/-clear-cache-option

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/
@@ -114,6 +114,10 @@ ENV/
 env.bak/
 venv.bak/
 
+# direnv
+.envrc
+.direnv/
+
 # Spyder project settings
 .spyderproject
 .spyproject

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,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
@@ -59,7 +60,7 @@ options:
   -k, --clear-cache
                         Delete 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
@@ -86,21 +87,23 @@ 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.
+  - 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`
@@ -135,10 +138,14 @@ 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.
 
+Alternatively, It is possible to use a different certificate store/bundle by setting:
+
+* `TLDR_CERT=/path/to/certificates.crt`
+
 ### Colors
 
 Values of the `TLDR_COLOR_x` variables may consist of three parts:
@@ -183,3 +190,7 @@ can either use the `--source` flag when using tldr or by specifying the followin
   - 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__
 

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.
+.