wikidot 3.1.0.dev9__tar.gz → 3.1.0.dev11__tar.gz

wikidot-3.1.0.dev11/PKG-INFO

@@ -0,0 +1,101 @@
+Metadata-Version: 2.2
+Name: wikidot
+Version: 3.1.0.dev11
+Summary: Wikidot Utility Library
+Author-email: ukwhatn <ukwhatn@gmail.com>
+Project-URL: Homepage, https://github.com/ukwhatn/wikidot.py
+Project-URL: Bug Tracker, https://github.com/ukwhatn/wikidot.py/issues
+Classifier: Development Status :: 3 - Alpha
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: License :: OSI Approved :: MIT License
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: httpx<0.29,>=0.25
+Requires-Dist: beautifulsoup4<4.14.0,>=4.12.2
+Requires-Dist: lxml<5.4.0,>=4.9.3
+Provides-Extra: build
+Requires-Dist: build; extra == "build"
+Requires-Dist: twine; extra == "build"
+Provides-Extra: lint
+Requires-Dist: ruff; extra == "lint"
+Requires-Dist: mypy; extra == "lint"
+Provides-Extra: format
+Requires-Dist: ruff; extra == "format"
+Provides-Extra: docs
+Requires-Dist: sphinx>=7.2.6; extra == "docs"
+Requires-Dist: sphinx-rtd-theme>=2.0.0; extra == "docs"
+Requires-Dist: sphinx-intl>=2.1.0; extra == "docs"
+Requires-Dist: myst-parser>=2.0.0; extra == "docs"
+Requires-Dist: sphinx-autodoc-typehints>=1.25.3; extra == "docs"
+
+# wikidot.py
+
+[![Documentation Status](https://github.com/ukwhatn/wikidot.py/actions/workflows/docs.yml/badge.svg)](https://ukwhatn.github.io/wikidot.py/)
+
+Pythonで簡単にWikidotサイトと対話するためのライブラリです。
+
+## 主な機能
+
+- サイト、ページ、ユーザー、フォーラムなどの情報取得と操作
+- ページの作成、編集、削除
+- フォーラムスレッドの取得、作成、返信
+- ユーザー管理とサイトメンバーシップ
+- プライベートメッセージの送受信
+- ログイン不要の機能と認証が必要な機能両方をサポート
+
+## インストール
+
+```bash
+pip install wikidot
+```
+
+## 使用例（基本）
+
+```python
+import wikidot
+
+# ログインなしでの使用
+client = wikidot.Client()
+
+# サイトとページの情報取得
+site = client.site.get("scp-jp")
+page = site.page.get("scp-173")
+
+print(f"タイトル: {page.title}")
+print(f"評価: {page.rating}")
+print(f"作成者: {page.created_by.name}")
+```
+
+## ドキュメント
+
+詳細な使用方法、APIリファレンス、例は公式ドキュメントをご覧ください：
+
+📚 **[公式ドキュメント](https://ukwhatn.github.io/wikidot.py/)**
+
+- [インストール方法](https://ukwhatn.github.io/wikidot.py/installation.html)
+- [クイックスタート](https://ukwhatn.github.io/wikidot.py/quickstart.html)
+- [使用例](https://ukwhatn.github.io/wikidot.py/examples.html)
+- [APIリファレンス](https://ukwhatn.github.io/wikidot.py/reference/index.html)
+
+## ドキュメント構築
+
+ローカルでドキュメントを構築するには:
+
+```bash
+# ドキュメント生成に必要なパッケージをインストール
+make docs-install
+
+# ドキュメントをビルド
+make docs-build
+
+# ローカルサーバーでドキュメントを確認（オプション）
+make docs-serve
+```
+
+## Contribution
+
+- [ロードマップ](https://ukwhatn.notion.site/wikidot-py-roadmap?pvs=4)
+- [Issue](https://github.com/ukwhatn/wikidot.py/issues)

wikidot-3.1.0.dev11/README.md

@@ -0,0 +1,68 @@
+# wikidot.py
+
+[![Documentation Status](https://github.com/ukwhatn/wikidot.py/actions/workflows/docs.yml/badge.svg)](https://ukwhatn.github.io/wikidot.py/)
+
+Pythonで簡単にWikidotサイトと対話するためのライブラリです。
+
+## 主な機能
+
+- サイト、ページ、ユーザー、フォーラムなどの情報取得と操作
+- ページの作成、編集、削除
+- フォーラムスレッドの取得、作成、返信
+- ユーザー管理とサイトメンバーシップ
+- プライベートメッセージの送受信
+- ログイン不要の機能と認証が必要な機能両方をサポート
+
+## インストール
+
+```bash
+pip install wikidot
+```
+
+## 使用例（基本）
+
+```python
+import wikidot
+
+# ログインなしでの使用
+client = wikidot.Client()
+
+# サイトとページの情報取得
+site = client.site.get("scp-jp")
+page = site.page.get("scp-173")
+
+print(f"タイトル: {page.title}")
+print(f"評価: {page.rating}")
+print(f"作成者: {page.created_by.name}")
+```
+
+## ドキュメント
+
+詳細な使用方法、APIリファレンス、例は公式ドキュメントをご覧ください：
+
+📚 **[公式ドキュメント](https://ukwhatn.github.io/wikidot.py/)**
+
+- [インストール方法](https://ukwhatn.github.io/wikidot.py/installation.html)
+- [クイックスタート](https://ukwhatn.github.io/wikidot.py/quickstart.html)
+- [使用例](https://ukwhatn.github.io/wikidot.py/examples.html)
+- [APIリファレンス](https://ukwhatn.github.io/wikidot.py/reference/index.html)
+
+## ドキュメント構築
+
+ローカルでドキュメントを構築するには:
+
+```bash
+# ドキュメント生成に必要なパッケージをインストール
+make docs-install
+
+# ドキュメントをビルド
+make docs-build
+
+# ローカルサーバーでドキュメントを確認（オプション）
+make docs-serve
+```
+
+## Contribution
+
+- [ロードマップ](https://ukwhatn.notion.site/wikidot-py-roadmap?pvs=4)
+- [Issue](https://github.com/ukwhatn/wikidot.py/issues)

{wikidot-3.1.0.dev9 → wikidot-3.1.0.dev11}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "wikidot"
-version = "3.1.0dev9"
+version = "3.1.0dev11"
 authors = [{ name = "ukwhatn", email = "ukwhatn@gmail.com" }]
 description = "Wikidot Utility Library"
 readme = "README.md"
@@ -15,7 +15,7 @@ classifiers = [
 
 dependencies = [
     "httpx >= 0.25,< 0.29",
-    "beautifulsoup4 ~= 4.12.2",
+    "beautifulsoup4 >= 4.12.2,< 4.14.0",
     "lxml >= 4.9.3,< 5.4.0",
 ]
 
@@ -25,15 +25,34 @@ build = [
     "twine",
 ]
 lint = [
-    "flake8",
+    "ruff",
     "mypy",
-    "isort",
 ]
 format = [
-    "black",
-    "isort",
+    "ruff",
+]
+docs = [
+    "sphinx>=7.2.6",
+    "sphinx-rtd-theme>=2.0.0",
+    "sphinx-intl>=2.1.0",
+    "myst-parser>=2.0.0",
+    "sphinx-autodoc-typehints>=1.25.3",
 ]
 
 [project.urls]
 "Homepage" = "https://github.com/ukwhatn/wikidot.py"
-"Bug Tracker" = "https://github.com/ukwhatn/wikidot.py/issues"
+"Bug Tracker" = "https://github.com/ukwhatn/wikidot.py/issues"
+
+[tool.ruff]
+target-version = "py310"
+line-length = 120
+lint.select = ["E", "F", "I"]
+lint.ignore = []
+
+[tool.ruff.format]
+quote-style = "double"
+indent-style = "space"
+line-ending = "auto"
+
+[tool.ruff.lint.isort]
+known-first-party = ["wikidot"]

wikidot-3.1.0.dev11/src/wikidot/__init__.py

@@ -0,0 +1,57 @@
+"""
+Wikidotサイトとの対話を行うためのPythonライブラリ
+
+このパッケージはWikidotサイトのAPI操作を抽象化し、直感的なインターフェースを提供する。
+ユーザー、サイト、ページなどのWikidotの主要要素にアクセスするための各種クラスが含まれている。
+"""
+
+import importlib
+import inspect
+import os
+import sys
+
+from .module.client import Client
+
+__all__ = ["Client"]
+__version__ = "3.1.0dev11"
+
+
+# 全クラス・モジュールを公開する
+def _import_submodules():
+    """
+    パッケージ内の全サブモジュールからクラスをインポートしトップレベルで公開する関数
+
+    各サブディレクトリ内のPythonファイルを走査し、含まれるクラスをトップレベルの名前空間に
+    インポートする。これにより、`wikidot.ClassName`のような形式でクラスにアクセスできる。
+
+    Notes
+    -----
+    '_'で始まるファイル名は無視される。
+    インポートに失敗した場合は静かに無視される。
+    """
+    current_module = sys.modules[__name__]
+    package_dir = os.path.dirname(__file__)
+
+    # 公開対象のディレクトリを走査
+    for base_dir in ["common", "connector", "module", "util"]:
+        base_path = os.path.join(package_dir, base_dir)
+        if not os.path.isdir(base_path):
+            continue
+
+        for filename in os.listdir(base_path):
+            if filename.startswith("_") or not filename.endswith(".py"):
+                continue
+
+            module_name = filename[:-3]  # .py を除去
+            full_module_name = f"{__name__}.{base_dir}.{module_name}"
+
+            try:
+                module = importlib.import_module(full_module_name)
+                for name, obj in inspect.getmembers(module, inspect.isclass):
+                    if obj.__module__ == full_module_name:
+                        setattr(current_module, name, obj)
+            except ImportError:
+                pass
+
+
+_import_submodules()

wikidot-3.1.0.dev11/src/wikidot/common/__init__.py

@@ -0,0 +1,10 @@
+"""
+Wikidotライブラリの共通機能モジュール
+
+このパッケージは、ライブラリ全体で使用される共通機能を提供する。
+例外クラス、デコレータ、ロギング機能などの汎用的な機能が含まれる。
+"""
+
+from .logger import logger as wd_logger
+
+__all__ = ["wd_logger"]

wikidot-3.1.0.dev11/src/wikidot/common/decorators.py

@@ -0,0 +1,77 @@
+"""
+各種デコレータを提供するモジュール
+
+このモジュールは、ライブラリ内で使用される共通のデコレータを提供する。
+現在は認証関連のデコレータが実装されている。
+"""
+
+from functools import wraps
+
+
+def login_required(func):
+    """
+    ログインが必要なメソッドや関数に適用するデコレータ
+
+    このデコレータを適用したメソッドや関数は、実行前に自動的にログイン状態をチェックする。
+    ログインしていない場合はLoginRequiredExceptionが送出される。
+
+    クライアントインスタンスは以下の優先順位で検索される：
+    1. client という名前の引数
+    2. Client クラスのインスタンスである引数
+    3. self.client（呼び出し元オブジェクトの属性）
+    4. selfが持つ属性が持つclientクラス（例：self.site.client）
+
+    Parameters
+    ----------
+    func : callable
+        デコレートする関数またはメソッド
+
+    Returns
+    -------
+    callable
+        ラップされた関数またはメソッド
+
+    Raises
+    ------
+    ValueError
+        クライアントインスタンスが見つからない場合
+    LoginRequiredException
+        ログインしていない場合（client.login_check()による）
+    """
+
+    @wraps(func)
+    def wrapper(*args, **kwargs):
+        client = None
+        if "client" in kwargs:
+            client = kwargs["client"]
+        else:
+            from wikidot.module.client import Client
+
+            for arg in args:
+                if isinstance(arg, Client):
+                    client = arg
+                    break
+
+            # selfに存在するか？
+            if client is None and args:
+                if hasattr(args[0], "client"):
+                    client = args[0].client
+                else:
+                    # selfが持つ属性にclientが存在するか探索する
+                    for attr_name in dir(args[0]):
+                        if attr_name.startswith("_"):
+                            continue
+                        attr = getattr(args[0], attr_name)
+                        if hasattr(attr, "client"):
+                            client = getattr(attr, "client")
+                            if isinstance(client, Client):
+                                break
+
+        if client is None:
+            raise ValueError("Client is not found")
+
+        client.login_check()
+
+        return func(*args, **kwargs)
+
+    return wrapper

wikidot-3.1.0.dev11/src/wikidot/common/exceptions.py

@@ -0,0 +1,259 @@
+# ---
+# 基底クラス
+# ---
+
+
+class WikidotException(Exception):
+    """
+    wikidot.py独自の例外の基底クラス
+
+    ライブラリ内で発生する全ての例外の親クラスとなる。
+    具体的な例外は各サブクラスで定義される。
+
+    Parameters
+    ----------
+    message : str
+        例外メッセージ
+    """
+
+    def __init__(self, message):
+        super().__init__(message)
+
+
+# ---
+# ワイルドカード
+# ---
+
+
+class UnexpectedException(WikidotException):
+    """
+    予期せぬ例外が発生したときに送出される例外
+
+    特定のエラー状態に分類できない、予期しない状況で発生する。
+    通常は内部エラーやバグを示す。
+
+    Parameters
+    ----------
+    message : str
+        例外メッセージ
+    """
+
+    def __init__(self, message):
+        super().__init__(message)
+
+
+# ---
+# セッション関連
+# ---
+
+
+class SessionCreateException(WikidotException):
+    """
+    セッションの作成に失敗したときに送出される例外
+
+    ログイン処理やセッション確立時に問題が発生した場合に使用される。
+    通常は認証情報の誤りやサーバー側の問題が原因となる。
+
+    Parameters
+    ----------
+    message : str
+        例外メッセージ
+    """
+
+    def __init__(self, message):
+        super().__init__(message)
+
+
+class LoginRequiredException(WikidotException):
+    """
+    ログインが必要なメソッドを未ログイン状態で呼び出したときに送出される例外
+
+    認証が必要な操作を実行する前に、ログイン状態をチェックする際に使用される。
+
+    Parameters
+    ----------
+    message : str
+        例外メッセージ
+    """
+
+    def __init__(self, message):
+        super().__init__(message)
+
+
+# ---
+# AMC関連
+# ---
+class AjaxModuleConnectorException(WikidotException):
+    """
+    Ajax Module Connectorへのリクエストに関連する例外の基底クラス
+
+    ajax-module-connector.phpへのAPIリクエスト処理中に発生する例外の親クラス。
+    具体的なエラー状態は各サブクラスで表現される。
+
+    Parameters
+    ----------
+    message : str
+        例外メッセージ
+    """
+
+    def __init__(self, message):
+        super().__init__(message)
+
+
+class AMCHttpStatusCodeException(AjaxModuleConnectorException):
+    """
+    AMCのHTTPステータスコードが200以外だった場合に送出される例外
+
+    Ajax Module ConnectorへのリクエストでHTTPレベルのエラーが発生した場合に使用される。
+
+    Parameters
+    ----------
+    message : str
+        例外メッセージ
+    status_code : int
+        エラーとなったHTTPステータスコード
+
+    Attributes
+    ----------
+    status_code : int
+        エラーとなったHTTPステータスコード
+    """
+
+    def __init__(self, message, status_code: int):
+        super().__init__(message)
+        self.status_code = status_code
+
+
+class WikidotStatusCodeException(AjaxModuleConnectorException):
+    """
+    AMCからのレスポンスのステータスが「ok」でなかった場合に送出される例外
+
+    HTTP通信自体は成功したが、Wikidot側で処理エラーが発生した場合に使用される。
+    HTTPステータスが200以外の場合は代わりにAMCHttpStatusCodeExceptionが使用される。
+
+    Parameters
+    ----------
+    message : str
+        例外メッセージ
+    status_code : str
+        Wikidotから返されたエラーステータスコード
+
+    Attributes
+    ----------
+    status_code : str
+        Wikidotから返されたエラーステータスコード
+    """
+
+    def __init__(self, message, status_code: str):
+        super().__init__(message)
+        self.status_code = status_code
+
+
+class ResponseDataException(AjaxModuleConnectorException):
+    """
+    AMCからのレスポンスデータが不正だった場合に送出される例外
+
+    レスポンスのパース失敗や、期待された形式と異なるデータが返された場合に使用される。
+
+    Parameters
+    ----------
+    message : str
+        例外メッセージ
+    """
+
+    def __init__(self, message):
+        super().__init__(message)
+
+
+# ---
+# ターゲットエラー関連
+# ---
+
+
+class NotFoundException(WikidotException):
+    """
+    要求されたリソースが見つからない場合に送出される例外
+
+    サイト、ページ、ユーザー、リビジョンなど、指定されたリソースが
+    Wikidot上に存在しない場合に使用される。
+
+    Parameters
+    ----------
+    message : str
+        例外メッセージ
+    """
+
+    def __init__(self, message):
+        super().__init__(message)
+
+
+class TargetExistsException(WikidotException):
+    """
+    既に存在するリソースを作成しようとした場合に送出される例外
+
+    新規作成操作が既存のリソースと衝突する場合に使用される。
+
+    Parameters
+    ----------
+    message : str
+        例外メッセージ
+    """
+
+    def __init__(self, message):
+        super().__init__(message)
+
+
+class TargetErrorException(WikidotException):
+    """
+    対象オブジェクトに操作を適用できない場合に送出される例外
+
+    リソースは存在するが、現在の状態では要求された操作を
+    実行できない場合に使用される（例：ロック中のページを編集しようとする）。
+
+    Parameters
+    ----------
+    message : str
+        例外メッセージ
+    """
+
+    def __init__(self, message):
+        super().__init__(message)
+
+
+class ForbiddenException(WikidotException):
+    """
+    権限不足により操作が拒否された場合に送出される例外
+
+    ユーザーが操作に必要な権限を持っていない場合や、
+    プライベートサイトへのアクセスが拒否された場合などに使用される。
+
+    Parameters
+    ----------
+    message : str
+        例外メッセージ
+    """
+
+    def __init__(self, message):
+        super().__init__(message)
+
+
+# ---
+# 処理エラー関連
+# ---
+
+
+class NoElementException(WikidotException):
+    """
+    必要な要素が見つからない場合に送出される例外
+
+    HTML解析時に期待された要素が見つからない場合など、
+    処理中に必要なデータが欠落している場合に使用される。
+
+    Parameters
+    ----------
+    message : str
+        例外メッセージ
+    """
+
+    def __init__(self, message):
+        super().__init__(message)

wikidot-3.1.0.dev11/src/wikidot/common/logger.py

@@ -0,0 +1,43 @@
+"""
+ロギング機能を提供するモジュール
+
+このモジュールは、ライブラリ全体で使用されるロガーを設定し、提供する。
+ログレベルの設定やフォーマットの指定などが可能。
+"""
+
+import logging
+
+
+def setup_logger(name: str = "wikidot", level=logging.INFO):
+    """
+    ロガーを設定する関数
+
+    指定された名前とログレベルでロガーを設定し、適切なフォーマットのハンドラを追加する。
+    デフォルトでは、時刻、ロガー名、ログレベル、メッセージを表示する形式となる。
+
+    Parameters
+    ----------
+    name : str, default "wikidot"
+        ロガーの名前
+    level : int, default logging.INFO
+        初期ログレベル
+
+    Returns
+    -------
+    logging.Logger
+        設定されたロガーインスタンス
+    """
+    _logger = logging.getLogger(name)
+    _logger.setLevel(level)
+
+    # ログフォーマット
+    formatter = logging.Formatter("%(asctime)s [%(name)s/%(levelname)s] %(message)s")
+    stream_handler = logging.StreamHandler()
+    stream_handler.setFormatter(formatter)
+    _logger.addHandler(stream_handler)
+
+    return _logger
+
+
+# パッケージ全体で使用されるデフォルトロガー
+logger = setup_logger()

wikidot-3.1.0.dev11/src/wikidot/connector/__init__.py

@@ -0,0 +1,7 @@
+"""
+Wikidotサイトとの通信を担当するコネクタモジュール
+
+このパッケージは、Wikidot APIおよびAjax機能との通信を行う
+低レベルなクライアントを提供する。モジュールパッケージのクラスは、
+これらのコネクタを介してWikidotサイトとの通信を行う。
+"""