muttlike-imap 1.0.0__tar.gz

muttlike_imap-1.0.0/.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,37 @@
+---
+name: Bug report
+about: Report a bug or unexpected behaviour in muttlike-imap
+title: ''
+labels: bug
+---
+
+## Environment
+
+- **muttlike-imap version**: <!-- output of `muttlike-imap --version` -->
+- **Python version**: <!-- output of `python3 --version` -->
+- **Operating system**: <!-- e.g. Ubuntu 24.04, macOS 14, Debian 12 -->
+- **IMAP server**: <!-- e.g. Dovecot, Cyrus, Gmail, Fastmail, etc. -->
+
+## Describe the bug
+
+<!-- A clear and concise description of what you expected and what actually happened. -->
+
+## Reproducer
+
+<!--
+The exact command line you ran. Redact mailbox or address details if
+you need to, but please keep the pattern argument intact -- it's the
+part most likely to be at fault.
+-->
+
+```sh
+muttlike-imap "..." --mailbox INBOX --summary
+```
+
+## Expected output
+
+<!-- What you expected the command to return or do. -->
+
+## Actual output
+
+<!-- The error message or wrong result you observed. Paste it in full. -->

muttlike_imap-1.0.0/.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,8 @@
+blank_issues_enabled: true
+contact_links:
+  - name: Pattern syntax reference
+    url: https://github.com/PierreSenellart/muttlike-imap/blob/main/docs/pattern-syntax.md
+    about: Full reference for the mutt-style pattern grammar.
+  - name: Storing the IMAP password securely
+    url: https://github.com/PierreSenellart/muttlike-imap/blob/main/docs/secrets.md
+    about: Worked examples with pass, gpg, and OS keyrings.

muttlike_imap-1.0.0/.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,30 @@
+---
+name: Feature request
+about: Suggest a new modifier, CLI flag, or behaviour improvement
+title: ''
+labels: enhancement
+---
+
+## Use case
+
+<!--
+What problem are you trying to solve? A concrete scenario
+("I want to find X but currently have to ...") helps more than an
+abstract request.
+-->
+
+## Proposed solution
+
+<!--
+What would the feature look like from a user's perspective? If you
+have a concrete CLI shape or pattern syntax in mind, show an example
+invocation.
+-->
+
+## Alternatives considered
+
+<!-- Other ways to solve the same problem; why they're less suitable. -->
+
+## Background / references
+
+<!-- Pointers to mutt's documentation, RFCs, or related tools that are relevant. Optional. -->

muttlike_imap-1.0.0/.github/dependabot.yml

@@ -0,0 +1,11 @@
+# To get started with Dependabot version updates, you'll need to specify which
+# package ecosystems to update and where the package manifests are located.
+# Please see the documentation for all configuration options:
+# https://docs.github.com/github/administering-a-repository/configuration-options-for-dependency-updates
+
+version: 2
+updates:
+  - package-ecosystem: "github-actions" # See documentation for possible values
+    directory: "/" # Location of package manifests
+    schedule:
+      interval: "weekly"

muttlike_imap-1.0.0/.github/pull_request_template.md

@@ -0,0 +1,29 @@
+<!-- Thanks for contributing to muttlike-imap! -->
+
+## Summary
+
+<!-- What does this PR change? One or two sentences. -->
+
+## Motivation
+
+<!--
+Why is this change necessary? Link to the related issue if applicable:
+
+    Closes #123
+    Fixes #456
+-->
+
+## Checklist
+
+- [ ] `pytest` passes locally (no IMAP server needed for the default suite)
+- [ ] `ruff check .` and `ruff format --check .` pass
+- [ ] Tests added or updated for any code change
+- [ ] `CHANGELOG.md` entry added under `[Unreleased]`
+- [ ] User-visible behaviour reflected in `README.md`, `docs/pattern-syntax.md`, or `docs/secrets.md` as appropriate
+
+## Notes for reviewers
+
+<!--
+Anything reviewers should pay extra attention to? Sharp edges,
+performance trade-offs, IMAP-protocol surprises, etc.
+-->

muttlike_imap-1.0.0/.github/workflows/ci.yml

@@ -0,0 +1,36 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+permissions:
+  contents: read
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+      - uses: actions/setup-python@v6
+        with:
+          python-version: "3.12"
+      - run: pip install ruff
+      - run: ruff check .
+      - run: ruff format --check .
+
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.9", "3.10", "3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v6
+      - uses: actions/setup-python@v6
+        with:
+          python-version: ${{ matrix.python-version }}
+      - run: pip install -e ".[dev]"
+      - run: pytest --cov --cov-report=term-missing

muttlike_imap-1.0.0/.github/workflows/release.yml

@@ -0,0 +1,47 @@
+name: Release
+
+on:
+  push:
+    tags:
+      - "v*"
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    name: Build sdist and wheel
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+      - uses: actions/setup-python@v6
+        with:
+          python-version: "3.12"
+      - name: Install build
+        run: python -m pip install --upgrade build
+      - name: Build distribution
+        run: python -m build
+      - name: Upload distribution artifacts
+        uses: actions/upload-artifact@v4
+        with:
+          name: distribution
+          path: dist/
+
+  publish:
+    name: Publish to PyPI
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/muttlike-imap
+    permissions:
+      id-token: write
+    steps:
+      - name: Download distribution artifacts
+        uses: actions/download-artifact@v4
+        with:
+          name: distribution
+          path: dist/
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

muttlike_imap-1.0.0/.gitignore

@@ -0,0 +1,17 @@
+__pycache__/
+*.py[cod]
+*$py.class
+*.egg-info/
+build/
+dist/
+.eggs/
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+.coverage
+htmlcov/
+.tox/
+.venv/
+venv/
+*.swp
+.DS_Store

muttlike_imap-1.0.0/CHANGELOG.md

@@ -0,0 +1,40 @@
+# Changelog
+
+All notable changes are documented here. The format is loosely based on
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project
+adheres to [Semantic Versioning](https://semver.org/).
+
+## [Unreleased]
+
+## [1.0.0]: Initial release
+
+First public release.
+
+### Added
+- Mutt-compatible pattern parser supporting AND (juxtaposition), `|` OR,
+  `!` NOT, and `(...)` grouping.
+- Text modifiers: `~f`, `~t`, `~s`, `~b`, `~B`, `~c`, `~C`, `~L`, `~e`, `~i`,
+  `~y`, `~h`, `~x`.
+- Flag modifiers: `~A`, `~U`, `~N`, `~R`, `~O`, `~F`, `~D`, `~Q`, `~p`, `~P`.
+- Date modifiers `~d` and `~r` with the full mutt DATERANGE grammar:
+  relative (`<Nu`, `>Nu`, `=Nu`), absolute (`D/M/Y` and ISO `YYYY-MM-DD`),
+  ranges, half-open ranges, and error margins (`*Nu`). Sub-day units
+  (`H`/`M`/`S`) get day-rounded server-side filtering plus a Python
+  post-filter against `Date:` (or `INTERNALDATE` for `~r`), recovering
+  precise sub-day windows like `~d <30M` for "last 30 minutes".
+- Size modifier `~z` with `<`, `>`, range, and inclusive/exclusive forms.
+- `--list-mailboxes` for folder discovery.
+- Modified UTF-7 (RFC 3501 §5.1.3) encoding/decoding for non-ASCII folder
+  names like `Éléments envoyés`.
+- ASCII diacritic folding so `~f Müller` matches both UTF-8 and ASCII forms.
+- Layered config: CLI flags > `IMAPQUERY_*` env vars > `$IMAPQUERY_CONFIG` >
+  `~/.config/muttlike-imap/config` > legacy `~/.config/imap-smtp-email/.env`.
+- `--imap-password-cmd` flag and `IMAP_PASS_CMD` config key for fetching the
+  password from `pass`, `gpg`, `secret-tool`, the macOS Keychain, etc.,
+  without storing it on disk or exporting it through the environment.
+- `--imap-password-env` flag for picking up an already-set environment
+  variable.
+- Library API: `parse_pattern`, `search`, `list_mailboxes`, `load_config`.
+
+[Unreleased]: https://github.com/PierreSenellart/muttlike-imap/compare/v1.0.0...HEAD
+[1.0.0]: https://github.com/PierreSenellart/muttlike-imap/releases/tag/v1.0.0

muttlike_imap-1.0.0/CODE_OF_CONDUCT.md

@@ -0,0 +1,30 @@
+# Code of Conduct
+
+`muttlike-imap` is a small open-source utility. Most interaction happens
+through GitHub issues and pull requests; this code of conduct sets the
+basic expectations for those exchanges.
+
+## Expected behavior
+
+- Be respectful and constructive in all interactions: issues, pull
+  requests, code reviews, and any other discussion.
+- Welcome newcomers, especially first-time contributors.
+- Accept constructive criticism gracefully; offer it the same way.
+
+## Unacceptable behavior
+
+- Harassment, intimidation, or discrimination of any kind.
+- Personal attacks or derogatory comments.
+- Publishing others' private information without consent.
+
+## Scope
+
+This code of conduct applies to all project spaces: the GitHub
+repository, issue tracker, pull requests, and any other communication
+channel associated with the project.
+
+## Enforcement
+
+Instances of unacceptable behavior may be reported to the project
+maintainer, [Pierre Senellart](mailto:pierre@senellart.com). Reports
+will be handled confidentially.

muttlike_imap-1.0.0/CONTRIBUTING.md

@@ -0,0 +1,56 @@
+# Contributing to muttlike-imap
+
+Thank you for your interest in contributing to muttlike-imap!
+
+## Reporting bugs and requesting features
+
+Please use the [GitHub issue
+tracker](https://github.com/PierreSenellart/muttlike-imap/issues). Two
+issue templates are provided and will auto-fill when you open a new
+issue: a bug-report form (asking for `muttlike-imap --version`, your
+Python version, OS, and a reproducer) and a feature-request form. For
+security vulnerabilities, please use the [private security
+advisory](https://github.com/PierreSenellart/muttlike-imap/security/advisories/new)
+flow instead of a public issue (see [SECURITY.md](SECURITY.md)).
+
+## Development setup
+
+```sh
+git clone https://github.com/PierreSenellart/muttlike-imap
+cd muttlike-imap
+pip install -e ".[dev]"
+```
+
+That installs `ruff` (lint + format) and `pytest` (with `pytest-cov`)
+into your current Python. The package itself has no runtime
+dependencies.
+
+## Running the tests and linters
+
+```sh
+pytest                        # full suite, ~240 tests, no IMAP server needed
+pytest --cov                  # with coverage
+ruff check .                  # lint
+ruff format --check .         # check formatting
+ruff format .                 # apply formatting
+```
+
+CI runs the same commands across Python 3.9 through 3.13.
+
+## Submitting a pull request
+
+1. Fork the repository and create a branch from `main`.
+2. Make your changes. Add or update tests for any code change: the bar
+   is "the test would have caught this bug" or "the test demonstrates
+   the new behaviour".
+3. Ensure `pytest`, `ruff check .`, and `ruff format --check .` pass.
+4. Update `CHANGELOG.md` under `[Unreleased]` with a one-line summary,
+   and update `README.md` / `docs/pattern-syntax.md` / `docs/secrets.md`
+   if you change user-visible behaviour.
+5. Open a pull request against `main` with a clear description of what
+   the change does and why.
+
+## License
+
+By contributing, you agree that your contributions will be licensed
+under the [MIT License](LICENSE).

muttlike_imap-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Pierre Senellart
+
+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.

muttlike_imap-1.0.0/PKG-INFO

@@ -0,0 +1,234 @@
+Metadata-Version: 2.4
+Name: muttlike-imap
+Version: 1.0.0
+Summary: Search IMAP mailboxes from the command line using mutt-style patterns.
+Project-URL: Homepage, https://github.com/PierreSenellart/muttlike-imap
+Project-URL: Issues, https://github.com/PierreSenellart/muttlike-imap/issues
+Project-URL: Changelog, https://github.com/PierreSenellart/muttlike-imap/blob/main/CHANGELOG.md
+Author-email: Pierre Senellart <pierre@senellart.com>
+License: MIT
+License-File: LICENSE
+Keywords: cli,email,imap,mutt,search
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: End Users/Desktop
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Communications :: Email
+Classifier: Topic :: Utilities
+Requires-Python: >=3.9
+Provides-Extra: dev
+Requires-Dist: pytest-cov; extra == 'dev'
+Requires-Dist: pytest>=7; extra == 'dev'
+Requires-Dist: ruff; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# muttlike-imap
+
+[![CI](https://github.com/PierreSenellart/muttlike-imap/actions/workflows/ci.yml/badge.svg)](https://github.com/PierreSenellart/muttlike-imap/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/muttlike-imap.svg)](https://pypi.org/project/muttlike-imap/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+
+Search IMAP mailboxes from the command line using mutt-style patterns.
+
+```console
+$ muttlike-imap "~f alice ~U" --summary
+1 result(s):
+
+UID:1264 | From:Alice <alice@example.com> | Date:Tue, 21 Apr 2026 15:02:35 +0000
+Subject:Re: project update
+Preview:Hi, here is the latest version of the document…
+```
+
+## Why
+
+Mutt has a great pattern language for finding messages (`~f`, `~s`, `~d <7d`,
+`!~U`, `(A | B) C`, …). IMAP servers can do most of the same searches, but the
+wire protocol is verbose and the bindings in `imaplib` are awkward to compose.
+`muttlike-imap` is a small CLI that translates mutt patterns into IMAP `SEARCH`
+criteria and prints the matches as JSON or a human-readable summary.
+
+It's intentionally small and scriptable – useful as a building block for
+notification scripts, AI assistants, cron jobs, or one-off lookups.
+
+## Install
+
+```sh
+pip install muttlike-imap
+```
+
+Requires Python 3.9+. No third-party dependencies.
+
+## Configure
+
+`muttlike-imap` looks for connection settings in this order (highest priority
+first):
+
+1. CLI flags: `--imap-host`, `--imap-port`, `--imap-user`,
+   `--imap-password-cmd`, `--imap-password-env`, `--imap-tls`.
+2. Environment variables: `IMAPQUERY_HOST`, `IMAPQUERY_PORT`, `IMAPQUERY_USER`,
+   `IMAPQUERY_PASS`, `IMAPQUERY_TLS`.
+3. The file pointed to by `$IMAPQUERY_CONFIG`, if set.
+4. `$XDG_CONFIG_HOME/muttlike-imap/config` (defaults to
+   `~/.config/muttlike-imap/config`).
+5. `~/.config/imap-smtp-email/.env`: kept as a fallback for users who already
+   have this file from the
+   [openclaw imap-smtp-email skill](https://github.com/openclaw/imap-smtp-email).
+   See [`docs/openclaw.md`](docs/openclaw.md) for wiring `muttlike-imap`
+   into an openclaw workspace.
+
+A minimal config file:
+
+```ini
+IMAP_HOST=imap.example.com
+IMAP_PORT=993
+IMAP_USER=you@example.com
+IMAP_PASS_CMD=pass email/imap.example.com
+IMAP_TLS=true
+```
+
+The keys can be written with the `IMAP_` prefix (shown above, matches mutt and
+offlineimap conventions), with the `IMAPQUERY_` prefix, or with no prefix at
+all (`HOST=…`); pick whichever you prefer.
+
+### Passwords
+
+There are three ways to give `muttlike-imap` your password, in increasing
+order of how much they leak:
+
+- **`IMAP_PASS_CMD=<shell command>`** (recommended). The command is run on
+  every invocation; the first line of stdout is used as the password. Pair
+  with [`pass`](https://www.passwordstore.org/),
+  [`secret-tool`](https://wiki.gnome.org/Projects/Libsecret),
+  macOS Keychain (`security find-generic-password -w`), or anything else
+  that prints a secret to stdout. The password lives only in the
+  `muttlike-imap` process memory and is never written to disk or to the
+  environment.
+
+  Equivalent CLI flag: `--imap-password-cmd "pass email/imap.example.com"`.
+
+- **`--imap-password-env MY_VAR`**. Reads the password from a named
+  environment variable. Useful when you already have a secret in a variable
+  (e.g. via `direnv` or a parent process) and don't want to re-export it.
+  Caveat: env vars leak through `/proc/<pid>/environ`, child processes,
+  `ps eww`, and crash dumps.
+
+- **`IMAP_PASS=<plaintext>`** in the config file. Simplest, least secure;
+  fine for throwaway accounts and local-only setups. Make sure the file is
+  `chmod 600`.
+
+See [`docs/secrets.md`](docs/secrets.md) for worked examples with `pass`,
+raw `gpg`, and OS keyrings.
+
+## Examples
+
+By default the search runs against `INBOX` and returns the 10 most recent
+matches as JSON. Pass `--mailbox <name>` to search elsewhere, `--limit N`
+to widen or narrow the result count, and `--summary` for human-readable
+output.
+
+```sh
+# Unread mail, default INBOX, summary view
+muttlike-imap "~U" --summary
+
+# All mail from Alice in the last week
+muttlike-imap "~f alice ~d <7d" --summary
+
+# Archived correspondence with Bob about a specific topic
+muttlike-imap '~L bob ~s "project x"' --mailbox Archive --summary
+
+# Anything addressed to me, last 30 days, that I haven't replied to
+muttlike-imap '~p ~d <30d !~Q' --summary
+
+# Date range, ISO format
+muttlike-imap '~d 2025-09-01-2025-12-31 ~f committee' --summary
+
+# JSON for piping into jq
+muttlike-imap "~U" | jq '.[] | {uid, subject, from}'
+
+# Discover available folders
+muttlike-imap --list-mailboxes
+```
+
+## Pattern syntax
+
+`A B` is AND (juxtaposition), `A | B` is OR, `!A` is NOT, and `(...)` groups.
+
+| Modifier | Meaning |
+|----------|---------|
+| `~f <text>` | From contains |
+| `~t <text>` | To contains |
+| `~s <text>` | Subject contains |
+| `~b <text>` | Body contains |
+| `~B <text>` | Body or any header contains |
+| `~c <text>` | Cc contains |
+| `~C <text>` | To, Cc, or Bcc contains |
+| `~L <text>` | Any participant (From/To/Cc) |
+| `~e <text>` | Sender header |
+| `~i <text>` | Message-ID |
+| `~y <text>` | X-Label |
+| `~h "Name: text"` | Arbitrary header |
+| `~x <text>` | References / In-Reply-To |
+| `~A` | All messages |
+| `~U` / `~N` | Unread / new |
+| `~R` / `~O` | Read / old |
+| `~F` | Flagged |
+| `~D` | Deleted |
+| `~Q` | Replied (answered) |
+| `~p` | Addressed to you |
+| `~P` | From you |
+| `~d <Nu` | Date: header newer than N units (units `y m w d H M S`) |
+| `~d >Nu` | Date: header older than N units |
+| `~d =Nu` | Exactly N units old |
+| `~d DATE` | On a specific date (`YYYY-MM-DD` or `D/M/Y`) |
+| `~d -DATE` / `~d DATE-` | Half-open range (before / since) |
+| `~d DATE-DATE` | Range |
+| `~d DATE*Nu` | Range of ±N units around DATE |
+| `~r DATERANGE` | Same grammar but on received date (INTERNALDATE) |
+| `~z <N` / `~z >N` / `~z N-M` | Size in bytes (suffix `K`/`M`) |
+
+See [`docs/pattern-syntax.md`](docs/pattern-syntax.md) for the full reference.
+
+### Limitations vs mutt
+
+* **No regex.** IMAP `SEARCH` is substring-only, so all text matches are
+  literal. Anchors and character classes are not honored.
+* **No mutt-runtime modifiers.** `~T` (tagged), `~v` (collapsed thread),
+  `~m` (message-number), `~n` (score), `~$`, `~#`, `~(...)` (thread patterns),
+  PGP modifiers: all error out instead of silently misbehaving.
+
+`H`/`M`/`S` offsets are exact despite IMAP's day granularity: the server
+narrows to the smallest whole-day window containing the precise range,
+then a client-side post-filter trims the fetched candidates by their
+`Date:` header (or `INTERNALDATE` for `~r`). `~d <30M` really does mean
+"last 30 minutes". The post-filter is suppressed when the sub-day
+modifier sits inside an `OR`, `!`, or paren-grouped disjunction, since
+lifting its predicate to a top-level filter would change the pattern's
+meaning.
+
+## Library use
+
+```python
+from muttlike_imap.parser import parse_pattern
+from muttlike_imap.client import search
+from muttlike_imap.config import load_config
+
+config = load_config()  # or pass in your own dict
+results = search(config, "~f alice ~U", limit=10, mailbox="INBOX")
+for r in results:
+    print(r["subject"])
+
+# Or just use the parser:
+parse_pattern("(~f a | ~f b) ~U")
+# → 'OR (FROM "a") (FROM "b") UNSEEN'
+```
+
+## License
+
+MIT: see [LICENSE](LICENSE).