hs-net 0.1.0__tar.gz

hs_net-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,91 @@
+name: CI
+
+on:
+  push:
+    branches: [dev]
+  pull_request:
+    branches: [main]
+  workflow_call:
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v4
+
+      - name: Set up Python
+        run: uv python install 3.13
+
+      - name: Install dependencies
+        run: uv sync --group dev
+
+      - name: Ruff lint
+        run: uv run ruff check src/
+
+      - name: Ruff format check
+        run: uv run ruff format --check src/
+
+      - name: Bandit security check
+        run: uv run bandit -c pyproject.toml -r src/
+
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.10", "3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v4
+
+      - name: Set up Python ${{ matrix.python-version }}
+        run: uv python install ${{ matrix.python-version }}
+
+      - name: Install dependencies
+        run: uv sync --group dev
+
+      - name: Run tests
+        run: uv run pytest tests/ -v --ignore=tests/test_client_integration.py
+
+  integration-test:
+    runs-on: ubuntu-latest
+    needs: [lint, test]
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v4
+
+      - name: Set up Python
+        run: uv python install 3.13
+
+      - name: Install dependencies
+        run: uv sync --group dev
+
+      - name: Run integration tests
+        run: uv run pytest tests/test_client_integration.py -v
+
+  build:
+    runs-on: ubuntu-latest
+    needs: [lint, test]
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v4
+
+      - name: Set up Python
+        run: uv python install 3.13
+
+      - name: Build package
+        run: uv build
+
+      - name: Upload artifacts
+        uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/

hs_net-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,81 @@
+name: Publish to PyPI
+
+on:
+  push:
+    branches: [main]
+  workflow_dispatch:
+
+jobs:
+  check:
+    runs-on: ubuntu-latest
+    outputs:
+      should_publish: ${{ steps.check_version.outputs.should_publish }}
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Check if version changed
+        id: check_version
+        run: |
+          # 获取当前版本
+          CURRENT_VERSION=$(grep -oP 'version = "\K[^"]+' pyproject.toml | head -1)
+          echo "Current version: $CURRENT_VERSION"
+
+          # 检查该版本 tag 是否已存在
+          if git tag -l "v$CURRENT_VERSION" | grep -q .; then
+            echo "Version v$CURRENT_VERSION already published, skipping."
+            echo "should_publish=false" >> $GITHUB_OUTPUT
+          else
+            echo "New version v$CURRENT_VERSION detected."
+            echo "should_publish=true" >> $GITHUB_OUTPUT
+          fi
+
+  ci:
+    needs: check
+    if: needs.check.outputs.should_publish == 'true'
+    uses: ./.github/workflows/ci.yml
+
+  publish:
+    runs-on: ubuntu-latest
+    needs: [check, ci]
+    if: needs.check.outputs.should_publish == 'true'
+    permissions:
+      id-token: write
+      contents: write
+    environment: pypi
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v4
+
+      - name: Set up Python
+        run: uv python install 3.13
+
+      - name: Build package
+        run: uv build
+
+      - name: Publish to PyPI
+        run: uv publish
+        env:
+          UV_PUBLISH_TOKEN: ${{ secrets.PYPI_API_TOKEN }}
+
+      - name: Get version
+        id: version
+        run: |
+          VERSION=$(grep -oP 'version = "\K[^"]+' pyproject.toml | head -1)
+          echo "version=$VERSION" >> $GITHUB_OUTPUT
+
+      - name: Create Git tag
+        run: |
+          git tag "v${{ steps.version.outputs.version }}"
+          git push origin "v${{ steps.version.outputs.version }}"
+
+      - name: Create GitHub Release
+        uses: softprops/action-gh-release@v2
+        with:
+          tag_name: "v${{ steps.version.outputs.version }}"
+          name: "v${{ steps.version.outputs.version }}"
+          files: dist/*
+          generate_release_notes: true

hs_net-0.1.0/.gitignore

@@ -0,0 +1,29 @@
+# Python
+__pycache__/
+*.py[oc]
+build/
+dist/
+wheels/
+*.egg-info
+
+# Virtual environments
+.venv
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+
+# Testing
+.pytest_cache/
+.coverage
+htmlcov/
+
+# Docs
+docs/node_modules/
+docs/doc_build/
+
+# OS
+.DS_Store
+Thumbs.db

hs_net-0.1.0/.pre-commit-config.yaml

@@ -0,0 +1,18 @@
+repos:
+  # bandit - 安全检查
+  - repo: https://github.com/PyCQA/bandit
+    rev: 1.7.10
+    hooks:
+      - id: bandit
+        args: ["-c", "pyproject.toml"]
+        exclude: ^tests/
+        additional_dependencies: ["bandit[toml]"]
+
+  # ruff - lint + format
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: 'v0.6.9'
+    hooks:
+      - id: ruff
+        args: [--fix, --exit-non-zero-on-fix, --show-fixes]
+      - id: ruff-format
+

hs_net-0.1.0/.python-version

@@ -0,0 +1 @@
+3.13

hs_net-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 昊色居士
+
+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.

hs_net-0.1.0/PKG-INFO

@@ -0,0 +1,200 @@
+Metadata-Version: 2.4
+Name: hs-net
+Version: 0.1.0
+Summary: 统一多引擎的增强型 HTTP 客户端，内置重试、选择器、信号中间件
+Project-URL: Homepage, https://github.com/x-haose/hs-net
+Project-URL: Repository, https://github.com/x-haose/hs-net
+Project-URL: Issues, https://github.com/x-haose/hs-net/issues
+Author-email: 昊色居士 <x-haose@users.noreply.github.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: aiohttp,async,http,httpx,network,scraping
+Classifier: Development Status :: 4 - Beta
+Classifier: Framework :: AsyncIO
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+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 :: Internet :: WWW/HTTP
+Requires-Python: >=3.10
+Requires-Dist: aiohttp>=3.9
+Requires-Dist: blinker>=1.8
+Requires-Dist: curl-cffi>=0.7
+Requires-Dist: fake-useragent>=1.5
+Requires-Dist: furl>=2.1
+Requires-Dist: httpx[http2,socks]>=0.28
+Requires-Dist: jmespath>=1.1.0
+Requires-Dist: parsel>=1.9
+Requires-Dist: pydantic>=2.9
+Requires-Dist: requests-go>=1.0
+Requires-Dist: requests>=2.31
+Requires-Dist: tenacity>=8.3
+Description-Content-Type: text/markdown
+
+# hs-net
+
+统一多引擎的增强型 HTTP 客户端，内置重试、选择器、信号中间件，同步异步全支持。
+
+## 特性
+
+- **多引擎切换** — httpx、aiohttp、curl-cffi、requests、requests-go，统一 API，一行切换
+- **同步 & 异步** — `Net`（异步）和 `SyncNet`（同步），接口完全一致
+- **智能选择器** — 内置 CSS、XPath、正则、JMESPath 四种数据提取
+- **自动重试** — 基于 tenacity，可配置次数、间隔、随机抖动
+- **信号中间件** — 请求前、响应后、重试时三个钩子
+- **反爬支持** — curl-cffi 浏览器 TLS 指纹模拟 + 随机 User-Agent
+
+## 安装
+
+```bash
+pip install hs-net
+```
+
+> Python >= 3.10，所有引擎开箱即用，无需额外安装。
+
+## 快速开始
+
+### 异步
+
+```python
+import asyncio
+from hs_net import Net
+
+async def main():
+    async with Net() as net:
+        resp = await net.get("https://example.com")
+        print(resp.css("title::text").get())  # Example Domain
+
+asyncio.run(main())
+```
+
+### 同步
+
+```python
+from hs_net import SyncNet
+
+with SyncNet() as net:
+    resp = net.get("https://example.com")
+    print(resp.css("title::text").get())  # Example Domain
+```
+
+## 引擎切换
+
+```python
+# httpx（默认）
+Net(engine="httpx")
+
+# aiohttp
+Net(engine="aiohttp")
+
+# curl-cffi（支持浏览器指纹模拟）
+Net(engine="curl_cffi", engine_options={"impersonate": "chrome120"})
+
+# requests（仅同步）
+SyncNet(engine="requests")
+
+# requests-go
+Net(engine="requests_go")
+```
+
+## 数据提取
+
+```python
+resp = await net.get("https://example.com")
+
+# CSS 选择器
+resp.css("title::text").get()
+
+# XPath
+resp.xpath("//h1/text()").get()
+
+# 正则
+resp.re_first(r"价格: (\d+)元")
+
+# JMESPath（JSON 响应）
+resp = await net.get("https://api.example.com/users")
+resp.jmespath("data[?age > `18`].name")
+```
+
+## 配置
+
+```python
+from hs_net import Net, NetConfig
+
+# 方式 1：构造函数参数
+net = Net(
+    engine="httpx",
+    base_url="https://api.example.com/v1",
+    timeout=30.0,
+    retries=5,
+    retry_delay=1.0,
+    user_agent="chrome",
+    verify=False,
+    concurrency=10,
+)
+
+# 方式 2：NetConfig 对象
+config = NetConfig(
+    engine="curl_cffi",
+    retries=3,
+    user_agent="random",
+    engine_options={"impersonate": "chrome120"},
+)
+net = Net(config=config)
+```
+
+参数优先级：`请求方法参数 > 构造函数参数 > NetConfig 默认值`
+
+## 信号中间件
+
+```python
+async with Net() as net:
+
+    @net.on_request_before
+    async def add_auth(req_data):
+        req_data.headers["Authorization"] = "Bearer token"
+        return req_data
+
+    @net.on_response_after
+    async def log_response(resp):
+        print(f"{resp.status_code} {resp.url}")
+
+    @net.on_request_retry
+    async def on_retry(exc):
+        print(f"重试: {exc}")
+
+    resp = await net.get("https://example.com")
+```
+
+## 错误处理
+
+```python
+from hs_net import Net, StatusException, RetryExhausted, RequestException
+
+async with Net() as net:
+    try:
+        resp = await net.get("https://httpbin.org/status/404")
+    except RetryExhausted as e:
+        print(f"{e.attempts} 次重试失败: {e.last_exception}")
+    except StatusException as e:
+        print(f"HTTP {e.code}")
+    except RequestException as e:
+        print(f"请求异常: {e}")
+```
+
+## 文档
+
+完整文档见 `docs/` 目录，本地预览：
+
+```bash
+cd docs
+pnpm install
+pnpm run dev
+```
+
+## License
+
+MIT

hs_net-0.1.0/README.md

@@ -0,0 +1,164 @@
+# hs-net
+
+统一多引擎的增强型 HTTP 客户端，内置重试、选择器、信号中间件，同步异步全支持。
+
+## 特性
+
+- **多引擎切换** — httpx、aiohttp、curl-cffi、requests、requests-go，统一 API，一行切换
+- **同步 & 异步** — `Net`（异步）和 `SyncNet`（同步），接口完全一致
+- **智能选择器** — 内置 CSS、XPath、正则、JMESPath 四种数据提取
+- **自动重试** — 基于 tenacity，可配置次数、间隔、随机抖动
+- **信号中间件** — 请求前、响应后、重试时三个钩子
+- **反爬支持** — curl-cffi 浏览器 TLS 指纹模拟 + 随机 User-Agent
+
+## 安装
+
+```bash
+pip install hs-net
+```
+
+> Python >= 3.10，所有引擎开箱即用，无需额外安装。
+
+## 快速开始
+
+### 异步
+
+```python
+import asyncio
+from hs_net import Net
+
+async def main():
+    async with Net() as net:
+        resp = await net.get("https://example.com")
+        print(resp.css("title::text").get())  # Example Domain
+
+asyncio.run(main())
+```
+
+### 同步
+
+```python
+from hs_net import SyncNet
+
+with SyncNet() as net:
+    resp = net.get("https://example.com")
+    print(resp.css("title::text").get())  # Example Domain
+```
+
+## 引擎切换
+
+```python
+# httpx（默认）
+Net(engine="httpx")
+
+# aiohttp
+Net(engine="aiohttp")
+
+# curl-cffi（支持浏览器指纹模拟）
+Net(engine="curl_cffi", engine_options={"impersonate": "chrome120"})
+
+# requests（仅同步）
+SyncNet(engine="requests")
+
+# requests-go
+Net(engine="requests_go")
+```
+
+## 数据提取
+
+```python
+resp = await net.get("https://example.com")
+
+# CSS 选择器
+resp.css("title::text").get()
+
+# XPath
+resp.xpath("//h1/text()").get()
+
+# 正则
+resp.re_first(r"价格: (\d+)元")
+
+# JMESPath（JSON 响应）
+resp = await net.get("https://api.example.com/users")
+resp.jmespath("data[?age > `18`].name")
+```
+
+## 配置
+
+```python
+from hs_net import Net, NetConfig
+
+# 方式 1：构造函数参数
+net = Net(
+    engine="httpx",
+    base_url="https://api.example.com/v1",
+    timeout=30.0,
+    retries=5,
+    retry_delay=1.0,
+    user_agent="chrome",
+    verify=False,
+    concurrency=10,
+)
+
+# 方式 2：NetConfig 对象
+config = NetConfig(
+    engine="curl_cffi",
+    retries=3,
+    user_agent="random",
+    engine_options={"impersonate": "chrome120"},
+)
+net = Net(config=config)
+```
+
+参数优先级：`请求方法参数 > 构造函数参数 > NetConfig 默认值`
+
+## 信号中间件
+
+```python
+async with Net() as net:
+
+    @net.on_request_before
+    async def add_auth(req_data):
+        req_data.headers["Authorization"] = "Bearer token"
+        return req_data
+
+    @net.on_response_after
+    async def log_response(resp):
+        print(f"{resp.status_code} {resp.url}")
+
+    @net.on_request_retry
+    async def on_retry(exc):
+        print(f"重试: {exc}")
+
+    resp = await net.get("https://example.com")
+```
+
+## 错误处理
+
+```python
+from hs_net import Net, StatusException, RetryExhausted, RequestException
+
+async with Net() as net:
+    try:
+        resp = await net.get("https://httpbin.org/status/404")
+    except RetryExhausted as e:
+        print(f"{e.attempts} 次重试失败: {e.last_exception}")
+    except StatusException as e:
+        print(f"HTTP {e.code}")
+    except RequestException as e:
+        print(f"请求异常: {e}")
+```
+
+## 文档
+
+完整文档见 `docs/` 目录，本地预览：
+
+```bash
+cd docs
+pnpm install
+pnpm run dev
+```
+
+## License
+
+MIT

hs_net-0.1.0/docs/.gitignore

@@ -0,0 +1,14 @@
+# Local
+.DS_Store
+*.local
+*.log*
+
+# Dist
+node_modules
+dist/
+doc_build/
+
+# IDE
+.vscode/*
+!.vscode/extensions.json
+.idea

hs_net-0.1.0/docs/README.md

@@ -0,0 +1,29 @@
+# Rspress website
+
+## Setup
+
+Install the dependencies:
+
+```bash
+npm install
+```
+
+## Get started
+
+Start the dev server:
+
+```bash
+npm run dev
+```
+
+Build the website for production:
+
+```bash
+npm run build
+```
+
+Preview the production build locally:
+
+```bash
+npm run preview
+```

hs_net-0.1.0/docs/docs/_nav.json

@@ -0,0 +1,17 @@
+[
+  {
+    "text": "指南",
+    "link": "/guide/introduction",
+    "activeMatch": "/guide/"
+  },
+  {
+    "text": "使用教程",
+    "link": "/usage/basic-request",
+    "activeMatch": "/usage/"
+  },
+  {
+    "text": "API 参考",
+    "link": "/api/net",
+    "activeMatch": "/api/"
+  }
+]

hs_net-0.1.0/docs/docs/api/_meta.json

@@ -0,0 +1 @@
+["net", "sync-net", "response", "config", "exceptions"]