Metadata-Version: 2.4
Name: share-cli
Version: 0.4.6
Summary: A simple file server
Author-email: Jackie Han <jackiehank@163.com>
License: The MIT License (MIT)
        Copyright © 2025 <copyright Jackie Hank>
        
        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.
        
Project-URL: Homepage, https://github.com/jackiehank/share
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: dev
Requires-Dist: pytest>=8.4.2; extra == "dev"
Requires-Dist: requests>=2.32.5; extra == "dev"
Requires-Dist: ruff>=0.12.12; extra == "dev"
Dynamic: license-file

# `share-cli` - 一键部署的单文件安全文件共享

[![Python](https://img.shields.io/badge/Python-3.8%2B-blue)](https://www.python.org/)
[![License](https://img.shields.io/badge/License-MIT-green)](LICENSE)

[English](/README-en.md)

**`share-cli` 是一个极致简单的单文件 HTTP 服务器。** 只需一个 Python 脚本，即可在局域网内快速、安全地共享您的文件夹。

```bash
# 使用 pipx 安装（强烈推荐）
pipx install share-cli

# 或使用 pip 安装
pip install --user share-cli
```

无需安装依赖，无需复杂配置。打开浏览器，即刻开始浏览、上传和播放您的文件。

## 🌐 使用场景

`share` 不仅仅是一个文件传输工具，更是一个轻量级的个人跨设备文件与媒体中心。它的核心价值在于：**让信息获取变得更简单**。很多时候，你需要的只是快速查看或播放一个文件，而不是繁琐地下载它。

以下是一些真实而常见的使用场景：

### 🏠 家庭共享
- **与家人分享美好瞬间**：周末聚会，用手机拍了一堆照片和视频。在Android设备上启动 `share` 共享照片文件夹，家人们就可以直接在各自的手机、平板、电脑或智能电视浏览器上**滑动浏览大图**、**连续播放视频**，无需等待下载，也无需在设备间来回传输文件。
- **打造家庭影音库**：在书房电脑上共享一个存放电影、剧集的文件夹。在客厅的平板或笔记本电脑上打开浏览器，直接**在线点播**，享受流畅的观影体验，省去了拷贝文件的麻烦。甚至可以使用手机下载电影后，用`share`共享，在平板或者电脑上观看。

### 👨‍🎓 个人多设备协同（特别适合学生党！）
- **平板竖屏看论文，电脑横屏做编辑**：这是 `share` 的杀手级应用场景。作为一名学生，你的电脑上存放着PDF论文、电子书和学习资料。在电脑上启动 `share` 后，你可以在平板上打开浏览器，**竖屏沉浸式阅读论文**，同时电脑屏幕可以腾出来专心进行文献整理或编写代码，学习效率翻倍。
- **手机临时查资料，电脑轻松共享**：在电脑上查阅资料时。无需发送文件到微信文件传输助手，直接用手机浏览器打开 `share` 地址，就能继续**浏览电脑上的PDF文档**(word、ppt导出为PDF即可)。
- **跨设备文件互传与预览**：手机拍摄的照片和视频，可以**直接上传**到电脑的共享目录，实现快速备份与整理。反过来，想在手机上预览电脑里的一段视频或一张图片，也无需下载，即点即看。

### 📱 快速临时的文件获取
- **手机需要电脑里的一个文件**：在电脑上共享文件所在目录，手机浏览器直接访问下载，比找数据线、登录QQ/微信文件传输更快更直接。
- **在其他电脑上临时取个文件**：在宿舍电脑共享文件，在实验室的电脑上(能搞定ip即可)打开浏览器下载，安全又方便。

**总而言之，`share` 化繁为简，将你的个人电脑瞬间变成一个专注于“访问”而非“管理”的轻量级服务器，让你在手机、平板、电脑之间架起一座无缝的桥梁，让局域网内的信息流动前所未有地直接和高效。**

## 🚀 为什么选择 `share`？

### ✅ 单文件，极致简洁
- **一个文件就是全部**：整个项目就是一个 `share.py` 脚本，没有复杂的目录结构。
- **零依赖**：仅依赖 Python 标准库，只要有 Python 环境，随时随地都能运行。
- **一键部署**：下载脚本，命令行运行，3 秒完成部署。

### 🔐 安全优先的设计理念
我深知数据安全的重要性。`share` 的设计哲学是：**在提供便利的同时，最大限度地降低风险**。

- **无破坏性操作**：`share` **不提供**文件删除、重命名或移动功能。
    - **为什么？** 这是**刻意为之的安全设计**。在开放的局域网环境中，任何修改操作都可能被滥用或误操作，导致不可逆的数据丢失。`share` 专注于“**安全共享**”，确保您的原始数据万无一失。
- **可选的访问控制**：
    - **密码保护**：使用 `--password` 参数，为您的共享添加一道访问屏障。
    - **HTTPS 加密**：使用 `--https` 参数，启用 HTTPS 加密传输，防止数据在局域网内被窃听或篡改。注意：启用后浏览器会提示“证书无效”，这是因为使用的是自签名证书。这是正常现象，请点击“高级” -> “继续访问”即可。此警告不影响加密的有效性，它依然能有效抵御局域网内的嗅探攻击。

### 🌟 强大而流畅的体验
尽管设计简洁，但功能毫不妥协：
- **分页浏览**：轻松浏览成千上万个文件，加载飞快。(包含大量文件的目录第一次加载较慢，之后有缓存就很快了)
- **多媒体中心**：内置图片、音视频播放器，支持滑动手势/方向键切换，ESC退出。
- **文本高亮**：代码、文本文件语法高亮显示，阅读更舒适；支持方向键切换，ESC退出。
- **拖拽上传**：将文件直接拖入浏览器即可上传到当前浏览目录，就像本地文件管理器一样方便。
- **一键下载**：点击文件列表中的文件即可下载，或者右键另存为。(目前只提供文件上传下载，不提供文件夹上传下载)

## ⚠️ 安全警告

`share` 设计用于**受信任的局域网环境**（如家庭、办公室）。
- **避免暴露在公网**：请勿将此服务器暴露在互联网上，因为它不包含企业级的安全审计和用户管理。
- **HTTPS 是关键**：当在不安全的网络（如公共WiFi）中使用时，**强烈建议启用 `--https`** 来加密您的数据传输。
- **密码保护**：在多用户环境中，使用 `--password` 防止未授权访问。

## 🚀 快速开始

### 📦 安装与部署

> **告别手动下载脚本！现在，你可以通过标准的 Python 包管理器一键安装 `share`。**

#### 1: 安装 `share-cli` 命令行工具

> **推荐通过 PyPI 一键安装，无需手动下载文件。**

你有两种推荐的安装方式：

**方式一：使用 `pipx` 安装（强烈推荐）**

`pipx` 是专为安装 Python 命令行工具设计的工具，它会为 `share` 创建一个独立的虚拟环境，避免污染你的主 Python 环境。

```bash
# 安装 pipx (如果尚未安装)
pip install pipx
pipx ensurepath

# 使用 pipx 从 PyPI 安装 share
pipx install share-cli
```

**方式二：使用 `pip` 安装**

如果你不想使用 `pipx`，也可以直接用 `pip` 安装：

```bash
pip install --user share-cli
```

> ✅ **安装完成后，即可在终端任何位置使用 `share` 命令！**
>
> `Android` 用户使用 `termux` 安装 `python` 后，同样可以使用上述 `pip` 命令进行安装。

---

#### （可选）手动下载安装包

如果你想手动下载 wheel 文件进行安装：

1.  访问项目的 [Gitee Release 页面](https://gitee.com/jackiehankk/share/releases) 或 [GitHub Releases 页面](https://github.com/jackiehank/share/releases)。
2.  在最新的版本（如 `v0.4.6`）下，找到 **Assets** 部分。
3.  下载文件 `share_cli-0.4.6-py3-none-any.whl`。
4.  使用 `pipx` 或 `pip` 安装下载的文件：

```bash
# 使用 pipx
pipx install ./share_cli-0.4.6-py3-none-any.whl

# 或使用 pip
pip install --user ./share_cli-0.4.6-py3-none-any.whl
```

#### 2: 开始使用！

安装完成后，你就可以在终端的任何位置使用 `share` 命令了！

```bash
# 共享当前目录
share .

# 共享指定文件夹、指定端口
share /path/to/your/folder -p 8080

# 启用密码保护
share ~/Documents --password

# 启用HTTPS加密(依赖 openssl，不启用则无需安装)
share ~/Pictures --https
```

#### 3. 访问共享

服务器启动后，会显示访问地址，例如：
```
Serving HTTP on 0.0.0.0 port 8000 (http://192.168.0.10:8000/)
```
在局域网内的其他设备上，打开浏览器访问该地址即可。

## 🛠 使用方法

```bash
usage: share [-h] [--password] [--https] [--cert CERT] [--key KEY] [-p PORT] [--host HOST] folder

位置参数:
  folder                要共享的文件夹路径

可选参数:
  --password            启用密码保护
  --https               启用HTTPS（自动生成自签名证书）
  --cert CERT           自定义HTTPS证书文件路径
  --key KEY             自定义HTTPS私钥文件路径
  -p PORT, --port PORT  服务器端口 (默认: 8000)
  --host HOST           监听地址 (默认: 0.0.0.0)
```

## 🤝 贡献

欢迎通过 Issues 报告问题或提出建议。

## 📄 许可证

MIT
