Implement

.github/FUNDING.yml

@@ -0,0 +1,4 @@
+github:
+- ofek
+custom:
+- https://ofek.dev/donate/

.github/dependabot.yml

@@ -0,0 +1,10 @@
+version: 2
+updates:
+- package-ecosystem: github-actions
+  directory: /
+  schedule:
+    interval: monthly
+  groups:
+    all:
+      patterns:
+      - "*"

.github/workflows/build.yml

@@ -0,0 +1,69 @@
+name: build
+
+on:
+  push:
+    tags:
+    - v*
+    branches:
+    - master
+  pull_request:
+    branches:
+    - master
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.event.pull_request.number || github.sha }}
+  cancel-in-progress: true
+
+defaults:
+  run:
+    shell: bash
+
+jobs:
+  build:
+    name: Build artifacts
+    runs-on: ubuntu-latest
+
+    steps:
+    - name: Checkout code
+      uses: actions/checkout@v4
+      with:
+        fetch-depth: 0
+
+    - name: Set up Python
+      uses: actions/setup-python@v5
+      with:
+        python-version: '3.12'
+
+    - name: Install Hatch
+      uses: pypa/hatch@install
+
+    - name: Build wheel and source distribution
+      run: hatch build
+
+    - name: Upload artifacts
+      uses: actions/upload-artifact@v4
+      with:
+        name: artifacts
+        path: dist/*
+        if-no-files-found: error
+
+  publish:
+    name: Publish to PyPI
+    if: github.event_name == 'push' && startsWith(github.event.ref, 'refs/tags')
+    needs: build
+    runs-on: ubuntu-latest
+
+    permissions:
+      id-token: write
+
+    steps:
+    - name: Download Python artifacts
+      uses: actions/download-artifact@v4
+      with:
+        name: artifacts
+        path: dist
+
+    - name: Push Python artifacts to PyPI
+      uses: pypa/[email protected]
+      with:
+        skip-existing: true

.github/workflows/docs.yml

@@ -0,0 +1,77 @@
+name: docs
+
+on:
+  push:
+    branches:
+    - master
+  pull_request:
+    branches:
+    - master
+
+concurrency:
+  group: docs-deploy
+
+env:
+  FORCE_COLOR: "1"
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+
+    steps:
+    - name: Checkout code
+      uses: actions/checkout@v4
+      with:
+        # Fetch all history for applying timestamps to every page
+        fetch-depth: 0
+
+    - name: Set up Python
+      uses: actions/setup-python@v5
+      with:
+        python-version: '3.12'
+
+    - name: Install Hatch
+      uses: pypa/hatch@install
+
+    - name: Configure Git for GitHub Actions bot
+      run: |
+        git config --local user.name 'github-actions[bot]'
+        git config --local user.email 'github-actions[bot]@users.noreply.github.com'
+
+    - name: Check documentation
+      run: hatch run docs:build-check
+
+    - name: Build documentation
+      run: hatch run docs:build
+
+    - name: Create archive
+      run: tar -czf site.tar.gz site
+
+    - name: Upload site
+      uses: actions/upload-artifact@v4
+      with:
+        name: site
+        path: site.tar.gz
+
+  publish:
+    if: github.event_name == 'push' && github.ref == 'refs/heads/master'
+    needs:
+    - build
+    runs-on: ubuntu-latest
+
+    permissions:
+      contents: write
+
+    steps:
+    - uses: actions/download-artifact@v4
+      with:
+        name: site
+
+    - name: Unpack archive
+      run: tar -xzf site.tar.gz
+
+    - uses: peaceiris/actions-gh-pages@v4
+      with:
+        github_token: ${{ secrets.GITHUB_TOKEN }}
+        publish_dir: site
+        commit_message: ${{ github.event.head_commit.message }}

.github/workflows/test.yml

@@ -0,0 +1,93 @@
+name: test
+
+on:
+  push:
+    branches:
+    - master
+  pull_request:
+    branches:
+    - master
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.event.pull_request.number || github.sha }}
+  cancel-in-progress: true
+
+env:
+  PYTHONUNBUFFERED: "1"
+  FORCE_COLOR: "1"
+
+jobs:
+  run:
+    name: Python ${{ matrix.python-version }} on ${{ startsWith(matrix.os, 'macos-') && 'macOS' || startsWith(matrix.os, 'windows-') && 'Windows' || 'Linux' }}
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, windows-latest, macos-latest]
+        python-version: ['3.8', '3.9', '3.10', '3.11', '3.12']
+
+    steps:
+    - name: Checkout code
+      uses: actions/checkout@v4
+
+    - name: Set up Python ${{ matrix.python-version }}
+      uses: actions/setup-python@v5
+      with:
+        python-version: ${{ matrix.python-version }}
+
+    - name: Install Hatch
+      uses: pypa/hatch@install
+
+    - name: Run static analysis
+      run: hatch fmt --check
+
+    - name: Check types
+      run: hatch run types:check
+
+    - name: Run tests
+      run: hatch test --python ${{ matrix.python-version }} --cover-quiet --randomize
+
+    - name: Create coverage report
+      run: hatch run hatch-test.py${{ matrix.python-version }}:coverage xml
+
+    - name: Upload coverage data
+      uses: actions/upload-artifact@v4
+      with:
+        name: coverage-${{ matrix.os }}-${{ matrix.python-version }}
+        path: coverage.xml
+
+  coverage:
+    name: Upload coverage
+    needs:
+    - run
+    runs-on: ubuntu-latest
+
+    permissions:
+      contents: read
+      id-token: write
+
+    steps:
+    - name: Download coverage data
+      uses: actions/download-artifact@v4
+      with:
+        pattern: coverage-*
+        path: coverage_data
+
+    - name: Upload coverage to Codecov
+      uses: codecov/codecov-action@v4
+      with:
+        directory: coverage_data
+        use_oidc: true
+
+  check:
+    if: always()
+    needs:
+    - run
+    - coverage
+    runs-on: ubuntu-latest
+
+    steps:
+    - name: Verify dependent success
+      uses: re-actors/alls-green@release/v1
+      with:
+        jobs: ${{ toJSON(needs) }}

.gitignore

@@ -0,0 +1,24 @@
+# Global directories
+__pycache__/
+
+# Global files
+*.py[cod]
+*.dll
+*.so
+*.log
+*.swp
+
+# Root directories
+/.benchmarks/
+/.cache/
+/.env/
+/.idea/
+/.mypy_cache/
+/.pytest_cache/
+/.ruff_cache/
+/.vscode/
+/dist/
+/site/
+
+# Root files
+/.coverage*

.linkcheckerrc

@@ -0,0 +1,2 @@
+# https://linkchecker.github.io/linkchecker/man/linkcheckerrc.html
+[AnchorCheck]

LICENSE.txt

@@ -0,0 +1,9 @@
+MIT License
+
+Copyright (c) 2024-present Ofek Lev <[email protected]>
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

README.md

@@ -0,0 +1,32 @@
+# find-exe
+
+| | |
+| --- | --- |
+| CI/CD | [![CI - Test](https://github.com/ofek/find-exe/actions/workflows/test.yml/badge.svg)](https://github.com/ofek/find-exe/actions/workflows/test.yml) [![CD - Build](https://github.com/ofek/find-exe/actions/workflows/build.yml/badge.svg)](https://github.com/ofek/find-exe/actions/workflows/build.yml) [![Coverage](https://img.shields.io/codecov/c/gh/ofek/find-exe?token=0CYRLWA98C)](https://app.codecov.io/gh/ofek/find-exe) |
+| Docs | [![Docs](https://github.com/ofek/find-exe/actions/workflows/docs.yml/badge.svg)](https://github.com/ofek/find-exe/actions/workflows/docs.yml) |
+| Package | [![PyPI - Version](https://img.shields.io/pypi/v/find-exe.svg?logo=pypi&label=PyPI&logoColor=gold)](https://pypi.org/project/find-exe/) [![PyPI - Python Version](https://img.shields.io/pypi/pyversions/find-exe.svg?logo=python&label=Python&logoColor=gold)](https://pypi.org/project/find-exe/) |
+| Meta | [![Hatch project](https://img.shields.io/badge/%F0%9F%A5%9A-Hatch-4051b5.svg)](https://github.com/ofek/find-exe) [![linting - Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff) [![types - Mypy](https://img.shields.io/badge/types-Mypy-blue.svg)](https://github.com/python/mypy) [![License - MIT](https://img.shields.io/badge/license-MIT-9400d3.svg)](https://spdx.org/licenses/) [![GitHub Sponsors](https://img.shields.io/github/sponsors/ofek?logo=GitHub%20Sponsors&style=social)](https://github.com/sponsors/ofek) |
+
+-----
+
+This provides a library and CLI (`find-exe`) to find all executables given certain criteria.
+
+```pycon
+>>> import find_exe
+>>> find_exe.with_prefix("py")
+['/usr/bin/python', ...]
+```
+
+## Installation
+
+```console
+pip install find-exe
+```
+
+## Documentation
+
+The [documentation](https://ofek.dev/find-exe/) is made with [Material for MkDocs](https://github.com/squidfunk/mkdocs-material) and is hosted by [GitHub Pages](https://docs.github.com/en/pages).
+
+## License
+
+`find-exe` is distributed under the terms of the [MIT](https://spdx.org/licenses/MIT.html) license.

docs/api.md

@@ -0,0 +1,7 @@
+# API
+
+-----
+
+::: find_exe
+    options:
+      filters: ["!^_"]

docs/assets/css/custom.css

@@ -0,0 +1,45 @@
+/* Brighter links for dark mode */
+[data-md-color-scheme=slate] {
+  /* https://github.com/squidfunk/mkdocs-material/blob/9.1.2/src/assets/stylesheets/main/_colors.scss#L91-L92 */
+  --md-typeset-a-color: var(--md-primary-fg-color--light);
+}
+
+/* FiraCode https://github.com/tonsky/FiraCode */
+code { font-family: 'Fira Code', monospace; }
+@supports (font-variation-settings: normal) {
+  code { font-family: 'Fira Code VF', monospace; }
+}
+
+/* https://github.com/squidfunk/mkdocs-material/issues/1522 */
+.md-typeset h5 {
+  color: var(--md-default-fg-color);
+  text-transform: none;
+}
+
+/* Indentation. */
+div.doc-contents:not(.first) {
+  padding-left: 25px;
+  border-left: .05rem solid var(--md-typeset-table-color);
+}
+
+/* Mark external links as such. */
+a.external::after,
+a.autorefs-external::after {
+  /* https://primer.style/octicons/arrow-up-right-24 */
+  mask-image: url('data:image/svg+xml,<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M18.25 15.5a.75.75 0 00.75-.75v-9a.75.75 0 00-.75-.75h-9a.75.75 0 000 1.5h7.19L6.22 16.72a.75.75 0 101.06 1.06L17.5 7.56v7.19c0 .414.336.75.75.75z"></path></svg>');
+  -webkit-mask-image: url('data:image/svg+xml,<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M18.25 15.5a.75.75 0 00.75-.75v-9a.75.75 0 00-.75-.75h-9a.75.75 0 000 1.5h7.19L6.22 16.72a.75.75 0 101.06 1.06L17.5 7.56v7.19c0 .414.336.75.75.75z"></path></svg>');
+  content: ' ';
+
+  display: inline-block;
+  vertical-align: middle;
+  position: relative;
+
+  height: 1em;
+  width: 1em;
+  background-color: currentColor;
+}
+
+a.external:hover::after,
+a.autorefs-external:hover::after {
+  background-color: var(--md-accent-fg-color);
+}

docs/changelog.md

@@ -0,0 +1,13 @@
+# Changelog
+
+-----
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## Unreleased
+
+## 0.1.0 - 2024-09-22
+
+This is the initial public release.