wslshot 0.0.11__py3-none-any.whl → 0.1.0__py3-none-any.whl

wslshot/exceptions.py

@@ -0,0 +1,25 @@
+"""Custom exceptions for wslshot."""
+
+
+class WslshotError(Exception):
+    """Base exception for wslshot errors."""
+
+
+class ConfigurationError(WslshotError):
+    """Configuration-related errors."""
+
+
+class ScreenshotNotFoundError(WslshotError):
+    """Screenshot not found errors."""
+
+
+class GitError(WslshotError):
+    """Git operation errors."""
+
+
+class ValidationError(WslshotError):
+    """Input validation errors."""
+
+
+class SecurityError(WslshotError):
+    """Security violation errors (symlinks, permissions, etc.)."""

wslshot-0.1.0.dist-info/METADATA

@@ -0,0 +1,282 @@
+Metadata-Version: 2.4
+Name: wslshot
+Version: 0.1.0
+Summary: Copy Windows screenshots into WSL for easy reuse.
+Author: Sébastien De Revière
+License-Expression: Apache-2.0
+Requires-Dist: click>=8.3.0
+Requires-Dist: click-default-group>=1.2.4
+Requires-Dist: pillow>=10.0.0
+Requires-Python: >=3.10
+Project-URL: Documentation, https://github.com/sderev/wslshot
+Project-URL: Issues, https://github.com/sderev/wslshot/issues
+Project-URL: Changelog, https://github.com/sderev/wslshot/blob/main/CHANGELOG.md
+Description-Content-Type: text/markdown
+
+# Windows Screenshot for Linux
+
+`wslshot` is a CLI tool designed to fetch the latest screenshot(s) from a directory shared with a Windows host, copy them to a designated directory in a Linux VM, and output their new paths in a configurable style (Markdown, HTML, or text).
+
+Take a screenshot using the Windows Snipping tool (`win + shift + S`), then run `wslshot` in your terminal to transfer the image.
+
+![demo](assets/images/demo.gif)
+
+<!-- TOC -->
+## Table of Contents
+
+1. [Features](#features)
+1. [AI Agent Snippet](#ai-agent-snippet)
+1. [Installation](#installation)
+    1. [Install with `pip`](#install-with-pip)
+    1. [Install with `uv`](#install-with-uv)
+1. [Quick Start](#quick-start)
+1. [Windows Configuration](#windows-configuration)
+    1. [For Windows 11 Users](#for-windows-11-users)
+    1. [For Windows 10 Users](#for-windows-10-users)
+1. [Shared Directory Configuration](#shared-directory-configuration)
+    1. [For WSL Users](#for-wsl-users)
+    1. [For Virtual Machine Users](#for-virtual-machine-users)
+1. [Configuration](#configuration)
+1. [Fetching Screenshots](#fetching-screenshots)
+1. [Using a Specific Image Path](#using-a-specific-image-path)
+    1. [Output](#output)
+    1. [File Copy Behavior](#file-copy-behavior)
+1. [Vim Integration](#vim-integration)
+<!-- /TOC -->
+
+## Features
+
+* Set a default source directory for screenshots.
+* Designate a custom source or destination directory per operation, or let wslshot detect typical image directories automatically.
+* Fetch the most recent screenshot or specify a number of recent screenshots to fetch.
+* Print source paths without copying files using `--no-transfer`.
+* Control automatic staging of screenshots when copied to a git repository.
+* Convert screenshots to `png`, `jpg`/`jpeg`, `webp`, or `gif` during copy (flag or default).
+* Optimize copied screenshots in place without changing filenames or extensions.
+* Set a default output style (Markdown, HTML, text) and specify a custom style per operation.
+* Migrate legacy config values with `migrate-config --dry-run`.
+
+## AI Agent Snippet
+
+Nice thing to have in your `AGENTS.md`:
+
+```md
+## Screenshots ("use/look at a screenshot")
+* Run `wslshot -n <number> --no-transfer` to pick n screenshots.
+* Run `wslshot --optimize` to copy the latest screenshot and optimize it when preparing docs/images.
+```
+
+### Example
+
+```text
+Look at my last screenshot.
+```
+
+The agent will run `wslshot -n 1 --no-transfer` and inspect it.
+
+## Installation
+
+Ensure you have Python 3.10 or later installed on your system.
+
+### Install with `pip`
+
+```bash
+python3 -m pip install wslshot
+```
+
+### Install with `uv`
+
+```bash
+uv tool install wslshot
+```
+
+## Quick Start
+
+This assumes your Windows screenshots are already saved in a directory your Linux environment can access.
+
+```bash
+wslshot configure --source /path --destination /path
+wslshot
+```
+
+## Windows Configuration
+
+Before using `wslshot`, you need to ensure that your screenshots are automatically saved to a directory accessible by your Linux environment.
+
+### For Windows 11 Users
+
+The Windows Snipping Tool in Windows 11 supports automatic saving of screenshots (it should be enabled by default):
+
+1. Open the Snipping Tool.
+1. Click on "Settings...".
+1. Toggle the box that says "Automatically save screenshots".
+
+### For Windows 10 Users
+
+The Snipping Tool in Windows 10 doesn't support automatic saving. However, you can use the following methods to automatically save screenshots:
+
+1. **Use `Win + PrtScn`**: It captures the entire screen and saves to `C:\Users\[Your Username]\Pictures\Screenshots`.
+1. **Use `Win + Alt + PrtScn`**: It captures the active window and saves to `C:\Users\[Your Username]\Videos\Captures`.
+    * To unify the save directory, right-click on the `Captures` directory, select **Properties**, and set your desired directory in the **Location** tab.
+1. **Use a third-party tool**.
+
+You can still use the Snipping Tool, but you'll need to manually save each screenshot after capturing it.
+
+## Shared Directory Configuration
+
+For `wslshot` to fetch screenshots from your Windows host, you need to set up a shared directory between your Windows host and your Linux VM.
+
+### For WSL Users
+
+If you are using the Windows Subsystem for Linux (WSL), you can directly access your Windows file system from your WSL distro. The Windows `C:` drive, for example, can be found at `/mnt/c/` within your WSL environment. Therefore, you can directly use a directory on your Windows file system as the source directory for `wslshot`.
+
+### For Virtual Machine Users
+
+If you are using a traditional virtual machine managed by a hypervisor (e.g., VirtualBox, VMware, Hyper-V), you'll need to set up a shared directory with your Windows host and the Linux VM. The process varies depending on your hypervisor, but here are general steps:
+
+1. Choose a directory on your Windows host to use as your screenshot directory. This should be the same directory where you configured your Snipping Tool to automatically save screenshots.
+1. Go into your VM settings and locate the shared directories option. Add the chosen screenshot directory as a shared directory.
+1. Depending on your VM settings, this directory will now be available at a certain path in your Linux environment. Use this path as your source directory for `wslshot`.
+
+Remember to consult the documentation of your hypervisor for specific instructions on how to set up shared directories.
+
+## Configuration
+
+Configure `wslshot` to suit your needs using the `configure` command:
+
+```bash
+wslshot configure [--source /path] [--destination /path] [--auto-stage-enabled True] [--output-style HTML] [--convert-to png]
+```
+
+This command allows you to set various options:
+
+* **`--source` or `-s`**: This option lets you specify the default source directory where `wslshot` will look for screenshots.
+
+* **`--destination` or `-d`**: This option lets you specify the default destination directory where `wslshot` will copy screenshots. When running inside a git repository, this default is ignored unless you pass `--destination` on that command; otherwise, `wslshot` uses repository image directories (`/img/`, `/images/`, `/assets/img/`, `/assets/images/`) in that order.
+
+* **`--auto-stage-enabled`**: This option lets you control whether screenshots are automatically staged when copied to a git repository. By default, this option is set to `False`. If this option is set to `True`, any screenshot copied to a git repository will automatically be staged for commit.
+
+* **`--output-style`**: This option lets you set the default output style for the links to the screenshots that `wslshot` creates. The available styles are Markdown, HTML, and text. If you do not set this option, `wslshot` will output links in Markdown format by default.
+
+* **`--convert-to` or `-c`**: Set the default image conversion format. Supported formats: png, jpg, jpeg, webp, gif. Conversion runs after copying; the converted file replaces the copied original. `jpeg` is treated as `jpg`. A CLI `--convert-to` flag overrides this default.
+
+These are default settings. Override them on a per-operation basis by providing the corresponding options when running the `wslshot` command.
+
+Migrate older configuration keys to the current names with `migrate-config`:
+
+```bash
+wslshot migrate-config --dry-run
+wslshot migrate-config
+```
+
+Use `--dry-run` to preview changes without writing the config file.
+
+## Fetching Screenshots
+
+**Fetch screenshots with the `wslshot` command**:
+
+```bash
+wslshot
+```
+
+This fetches the most recent screenshot from the source directory. If run inside a git repository, wslshot looks for an existing image directory (checked in priority order) and copies the screenshot there. If none exists, it creates `/assets/images/`.
+
+**Directories checked in priority order**:
+
+1. `/img/`
+2. `/images/`
+3. `/assets/img/`
+4. `/assets/images/`
+
+**You can also choose a specific number of screenshots**:
+
+```bash
+wslshot -n 3
+```
+
+This fetches the three most recent screenshots.
+
+**Print source paths without copying files**:
+
+```bash
+wslshot --no-transfer
+```
+
+This prints the source paths for the selected screenshots without copying files or interacting with git. Output defaults to text; override with `--output-style`.
+
+This mode rejects flags that require transfer (`--destination`, `--convert-to`, `--optimize`).
+
+**Convert screenshots to a different format**:
+
+```bash
+wslshot --convert-to png
+```
+
+This converts the screenshot(s) to the specified format. Supported formats: png, jpg, jpeg, webp, gif. If a default conversion is set in configuration, it runs when no flag is provided. Conversion happens after copying, and the converted file replaces the copied original. If auto-staging is enabled in a git repository, only the converted file is staged. Conversion is skipped only when the copied file already has the target extension; `.jpeg` files are rewritten to `.jpg`. Conversion applies both to the latest-screenshot workflow and when you pass a specific image path.
+
+**Optimize copied screenshots in place**:
+
+```bash
+wslshot --optimize
+```
+
+This optimizes copied screenshots after transfer and rewrites destination files in place. Source files are never modified. Optimization preserves each copied file's extension. If a default conversion format is configured, `--optimize` takes precedence for that run and skips conversion.
+
+`--optimize` conflicts with `--no-transfer` and `--convert-to`.
+
+**Allow symlinks (security risk)**:
+
+```bash
+wslshot --allow-symlinks
+```
+
+WARNING: Only use with trusted paths. By default, `wslshot` rejects symlinks for security.
+
+**These are all the possible options**:
+
+```bash
+wslshot [--source /custom/source] [--destination /custom/destination] [--count 3] [--output-style HTML] [--no-transfer] [--convert-to png] [--optimize] [--allow-symlinks]
+```
+
+Notes:
+
+* `--no-transfer` cannot be combined with `--destination`, `--convert-to`, or `--optimize`.
+* `--optimize` cannot be combined with `--convert-to`.
+
+## Using a Specific Image Path
+
+Provide the path to a specific image as an argument:
+
+```bash
+wslshot /mnt/c/user/my_name/Images/magic.gif
+```
+
+Note that you can _drag and drop_ a file into the Windows Terminal to automatically populate its path.
+
+### Output
+
+Upon success, the command outputs the new path in your configured output style (Markdown by default). Override per run with `--output-style`:
+
+```
+![<uuid>.gif](/assets/images/<uuid>.gif)
+```
+
+### File Copy Behavior
+
+The specified image is copied to your designated directory on the Linux VM.
+
+Supported source image formats are PNG, JPEG/JPG, and GIF.
+
+## Vim Integration
+
+If `wslshot` is in your PATH, call it with a filter command:
+
+```vim
+:.!wslshot
+```
+
+![vim demo](assets/images/demo-vim.gif)
+
+---
+
+<https://github.com/sderev/wslshot>

wslshot-0.1.0.dist-info/RECORD

@@ -0,0 +1,7 @@
+wslshot/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+wslshot/cli.py,sha256=74y-a8m6RusAZRemMpNYfP3guIM2EEIRH06LmDLjdV4,87695
+wslshot/exceptions.py,sha256=i28RvmvichlKkRzWjkbU2LsMS9dliENz8BeWAk-KdME,525
+wslshot-0.1.0.dist-info/WHEEL,sha256=iHtWm8nRfs0VRdCYVXocAWFW8ppjHL-uTJkAdZJKOBM,80
+wslshot-0.1.0.dist-info/entry_points.txt,sha256=i9-PCDJjxAkeZCNOe98GOxNBUVOLPuOr9Vb022lDmeY,49
+wslshot-0.1.0.dist-info/METADATA,sha256=R-GfJAUr94zpV5tE-6LzAdZcMzutrCA6bWzc6o0jkCE,11331
+wslshot-0.1.0.dist-info/RECORD,,

{wslshot-0.0.11.dist-info → wslshot-0.1.0.dist-info}/WHEEL

@@ -1,5 +1,4 @@
 Wheel-Version: 1.0
-Generator: bdist_wheel (0.41.2)
+Generator: uv 0.9.30
 Root-Is-Purelib: true
 Tag: py3-none-any
-

{wslshot-0.0.11.dist-info → wslshot-0.1.0.dist-info}/entry_points.txt

@@ -1,2 +1,3 @@
 [console_scripts]
 wslshot = wslshot.cli:wslshot
+

wslshot-0.0.11.dist-info/LICENSE

@@ -1,201 +0,0 @@
-                                 Apache License
-                           Version 2.0, January 2004
-                        http://www.apache.org/licenses/
-
-   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
-
-   1. Definitions.
-
-      "License" shall mean the terms and conditions for use, reproduction,
-      and distribution as defined by Sections 1 through 9 of this document.
-
-      "Licensor" shall mean the copyright owner or entity authorized by
-      the copyright owner that is granting the License.
-
-      "Legal Entity" shall mean the union of the acting entity and all
-      other entities that control, are controlled by, or are under common
-      control with that entity. For the purposes of this definition,
-      "control" means (i) the power, direct or indirect, to cause the
-      direction or management of such entity, whether by contract or
-      otherwise, or (ii) ownership of fifty percent (50%) or more of the
-      outstanding shares, or (iii) beneficial ownership of such entity.
-
-      "You" (or "Your") shall mean an individual or Legal Entity
-      exercising permissions granted by this License.
-
-      "Source" form shall mean the preferred form for making modifications,
-      including but not limited to software source code, documentation
-      source, and configuration files.
-
-      "Object" form shall mean any form resulting from mechanical
-      transformation or translation of a Source form, including but
-      not limited to compiled object code, generated documentation,
-      and conversions to other media types.
-
-      "Work" shall mean the work of authorship, whether in Source or
-      Object form, made available under the License, as indicated by a
-      copyright notice that is included in or attached to the work
-      (an example is provided in the Appendix below).
-
-      "Derivative Works" shall mean any work, whether in Source or Object
-      form, that is based on (or derived from) the Work and for which the
-      editorial revisions, annotations, elaborations, or other modifications
-      represent, as a whole, an original work of authorship. For the purposes
-      of this License, Derivative Works shall not include works that remain
-      separable from, or merely link (or bind by name) to the interfaces of,
-      the Work and Derivative Works thereof.
-
-      "Contribution" shall mean any work of authorship, including
-      the original version of the Work and any modifications or additions
-      to that Work or Derivative Works thereof, that is intentionally
-      submitted to Licensor for inclusion in the Work by the copyright owner
-      or by an individual or Legal Entity authorized to submit on behalf of
-      the copyright owner. For the purposes of this definition, "submitted"
-      means any form of electronic, verbal, or written communication sent
-      to the Licensor or its representatives, including but not limited to
-      communication on electronic mailing lists, source code control systems,
-      and issue tracking systems that are managed by, or on behalf of, the
-      Licensor for the purpose of discussing and improving the Work, but
-      excluding communication that is conspicuously marked or otherwise
-      designated in writing by the copyright owner as "Not a Contribution."
-
-      "Contributor" shall mean Licensor and any individual or Legal Entity
-      on behalf of whom a Contribution has been received by Licensor and
-      subsequently incorporated within the Work.
-
-   2. Grant of Copyright License. Subject to the terms and conditions of
-      this License, each Contributor hereby grants to You a perpetual,
-      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
-      copyright license to reproduce, prepare Derivative Works of,
-      publicly display, publicly perform, sublicense, and distribute the
-      Work and such Derivative Works in Source or Object form.
-
-   3. Grant of Patent License. Subject to the terms and conditions of
-      this License, each Contributor hereby grants to You a perpetual,
-      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
-      (except as stated in this section) patent license to make, have made,
-      use, offer to sell, sell, import, and otherwise transfer the Work,
-      where such license applies only to those patent claims licensable
-      by such Contributor that are necessarily infringed by their
-      Contribution(s) alone or by combination of their Contribution(s)
-      with the Work to which such Contribution(s) was submitted. If You
-      institute patent litigation against any entity (including a
-      cross-claim or counterclaim in a lawsuit) alleging that the Work
-      or a Contribution incorporated within the Work constitutes direct
-      or contributory patent infringement, then any patent licenses
-      granted to You under this License for that Work shall terminate
-      as of the date such litigation is filed.
-
-   4. Redistribution. You may reproduce and distribute copies of the
-      Work or Derivative Works thereof in any medium, with or without
-      modifications, and in Source or Object form, provided that You
-      meet the following conditions:
-
-      (a) You must give any other recipients of the Work or
-          Derivative Works a copy of this License; and
-
-      (b) You must cause any modified files to carry prominent notices
-          stating that You changed the files; and
-
-      (c) You must retain, in the Source form of any Derivative Works
-          that You distribute, all copyright, patent, trademark, and
-          attribution notices from the Source form of the Work,
-          excluding those notices that do not pertain to any part of
-          the Derivative Works; and
-
-      (d) If the Work includes a "NOTICE" text file as part of its
-          distribution, then any Derivative Works that You distribute must
-          include a readable copy of the attribution notices contained
-          within such NOTICE file, excluding those notices that do not
-          pertain to any part of the Derivative Works, in at least one
-          of the following places: within a NOTICE text file distributed
-          as part of the Derivative Works; within the Source form or
-          documentation, if provided along with the Derivative Works; or,
-          within a display generated by the Derivative Works, if and
-          wherever such third-party notices normally appear. The contents
-          of the NOTICE file are for informational purposes only and
-          do not modify the License. You may add Your own attribution
-          notices within Derivative Works that You distribute, alongside
-          or as an addendum to the NOTICE text from the Work, provided
-          that such additional attribution notices cannot be construed
-          as modifying the License.
-
-      You may add Your own copyright statement to Your modifications and
-      may provide additional or different license terms and conditions
-      for use, reproduction, or distribution of Your modifications, or
-      for any such Derivative Works as a whole, provided Your use,
-      reproduction, and distribution of the Work otherwise complies with
-      the conditions stated in this License.
-
-   5. Submission of Contributions. Unless You explicitly state otherwise,
-      any Contribution intentionally submitted for inclusion in the Work
-      by You to the Licensor shall be under the terms and conditions of
-      this License, without any additional terms or conditions.
-      Notwithstanding the above, nothing herein shall supersede or modify
-      the terms of any separate license agreement you may have executed
-      with Licensor regarding such Contributions.
-
-   6. Trademarks. This License does not grant permission to use the trade
-      names, trademarks, service marks, or product names of the Licensor,
-      except as required for reasonable and customary use in describing the
-      origin of the Work and reproducing the content of the NOTICE file.
-
-   7. Disclaimer of Warranty. Unless required by applicable law or
-      agreed to in writing, Licensor provides the Work (and each
-      Contributor provides its Contributions) on an "AS IS" BASIS,
-      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
-      implied, including, without limitation, any warranties or conditions
-      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
-      PARTICULAR PURPOSE. You are solely responsible for determining the
-      appropriateness of using or redistributing the Work and assume any
-      risks associated with Your exercise of permissions under this License.
-
-   8. Limitation of Liability. In no event and under no legal theory,
-      whether in tort (including negligence), contract, or otherwise,
-      unless required by applicable law (such as deliberate and grossly
-      negligent acts) or agreed to in writing, shall any Contributor be
-      liable to You for damages, including any direct, indirect, special,
-      incidental, or consequential damages of any character arising as a
-      result of this License or out of the use or inability to use the
-      Work (including but not limited to damages for loss of goodwill,
-      work stoppage, computer failure or malfunction, or any and all
-      other commercial damages or losses), even if such Contributor
-      has been advised of the possibility of such damages.
-
-   9. Accepting Warranty or Additional Liability. While redistributing
-      the Work or Derivative Works thereof, You may choose to offer,
-      and charge a fee for, acceptance of support, warranty, indemnity,
-      or other liability obligations and/or rights consistent with this
-      License. However, in accepting such obligations, You may act only
-      on Your own behalf and on Your sole responsibility, not on behalf
-      of any other Contributor, and only if You agree to indemnify,
-      defend, and hold each Contributor harmless for any liability
-      incurred by, or claims asserted against, such Contributor by reason
-      of your accepting any such warranty or additional liability.
-
-   END OF TERMS AND CONDITIONS
-
-   APPENDIX: How to apply the Apache License to your work.
-
-      To apply the Apache License to your work, attach the following
-      boilerplate notice, with the fields enclosed by brackets "[]"
-      replaced with your own identifying information. (Don't include
-      the brackets!)  The text should be enclosed in the appropriate
-      comment syntax for the file format. We also recommend that a
-      file or class name and description of purpose be included on the
-      same "printed page" as the copyright notice for easier
-      identification within third-party archives.
-
-   Copyright [yyyy] [name of copyright owner]
-
-   Licensed under the Apache License, Version 2.0 (the "License");
-   you may not use this file except in compliance with the License.
-   You may obtain a copy of the License at
-
-       http://www.apache.org/licenses/LICENSE-2.0
-
-   Unless required by applicable law or agreed to in writing, software
-   distributed under the License is distributed on an "AS IS" BASIS,
-   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-   See the License for the specific language governing permissions and
-   limitations under the License.