steam-editor-tools 0.1.0__py3-none-any.whl

steam_editor_tools/__init__.py

@@ -0,0 +1,76 @@
+# -*- coding: UTF-8 -*-
+"""
+Steam Editor Tools
+======
+
+Author
+------
+Yuchen Jin (cainmagi)
+cainmagi@gmail.com
+
+License
+-------
+MIT License
+
+Description
+-----------
+This package offers editor tools helping users write Steam guides and reviews.
+
+This package support Steam information queries, image editing tools, and BBCode
+text processing tools. Users can write their documents with Markdown, use this
+package to process the images in the document, and convert the document to the
+Steam BBCode format.
+"""
+
+from pkgutil import extend_path
+
+from . import version
+from . import utils
+from . import bbcode
+from . import improc
+from . import steaminfo
+
+from .version import __version__
+from .bbcode import DocumentParser, GuideParser, BBCodeRenderer, BBCodeConfig
+from .improc import (
+    ImageFontAbsSize,
+    ImageFontSize,
+    ImageFormat,
+    ImageQuality,
+    ImageAnchor,
+    ImageSingle,
+    ImageText,
+    ImageTeX,
+    ImageMultiLayer,
+)
+from .steaminfo import query_app_by_name_simple, get_app_details
+
+__all__ = (
+    "version",
+    "utils",
+    "bbcode",
+    "improc",
+    "steaminfo",
+    "__version__",
+    "DocumentParser",
+    "GuideParser",
+    "BBCodeRenderer",
+    "BBCodeConfig",
+    "ImageFontAbsSize",
+    "ImageFontSize",
+    "ImageFormat",
+    "ImageQuality",
+    "ImageAnchor",
+    "ImageSingle",
+    "ImageText",
+    "ImageTeX",
+    "ImageMultiLayer",
+    "query_app_by_name_simple",
+    "get_app_details",
+)
+
+# Set this local module as the prefered one
+__path__ = extend_path(__path__, __name__)
+
+# Delete private sub-modules and objects
+del extend_path

steam_editor_tools/utils.py

@@ -0,0 +1,104 @@
+# -*- coding: UTF-8 -*-
+"""
+Utilities
+=========
+@ Steam Editor Tools
+
+Author
+------
+Yuchen Jin (cainmagi)
+cainmagi@gmail.com
+
+License
+-------
+MIT License
+
+Description
+-----------
+The utilities of this package. The utilities in this module are designed for
+general use.
+"""
+
+import os
+import contextlib
+import tempfile
+import shutil
+import types
+
+from typing import TypeVar
+
+
+_BaseException = TypeVar("_BaseException", bound=BaseException)
+__all__ = ("NamedTempFolder",)
+
+
+class NamedTempFolder(contextlib.AbstractContextManager):
+    """Named temporary folder.
+
+    Similar to `tempfile.NamedTemporaryFile`. This context maintain a temporary
+    folder that can be accessed by the path. When exiting from the context, the
+    temporary folder will be automatically deleted.
+    """
+
+    __slots__ = ("folder_path", "__current_path")
+
+    def __init__(self, folder_path: "str | os.PathLike[str] | None" = None) -> None:
+        """Initialization.
+
+        Arguments
+        ---------
+        folder_path: `str | PathLike[str] | None`
+            The path to the temporary folder. If not specified, will use
+            `tempfile.mkdtemp()` to create the folder.
+
+            Note that if the specified folder path exists, will automatically add
+            postfix to the given path until a new folder can be maintained.
+        """
+        if folder_path:
+            folder_path = str(folder_path)
+            base_path = folder_path
+            num = 0
+            while os.path.exists(folder_path):
+                folder_path = os.path.join(base_path, "temp{0:03d}".format(num))
+                num = num + 1
+        else:
+            folder_path = None
+        self.folder_path: str | None = folder_path
+        self.__current_path: str | None = None
+
+    @property
+    def current_path(self) -> str | None:
+        """Property: Get the current temporary folder path. If not in the context,
+        this value will be `None`."""
+        return self.__current_path
+
+    def close(self) -> None:
+        """Close the temporary folder. Will delete the folder and reset the status
+        to the status that is not in the context.
+
+        This method will be automatically called when exiting from this context.
+        """
+        if isinstance(self.__current_path, str) and self.__current_path:
+            shutil.rmtree(self.__current_path, ignore_errors=True)
+        self.__current_path = None
+
+    def __enter__(self) -> str:
+        """Enter the context."""
+        self.close()
+        if self.folder_path is None:
+            current_path = tempfile.mkdtemp(suffix=None, prefix=None, dir=None)
+        else:
+            current_path = self.folder_path
+            os.makedirs(current_path, exist_ok=True)
+        self.__current_path = current_path
+        return current_path
+
+    def __exit__(
+        self,
+        exc_type: type[_BaseException] | None,
+        exc_value: _BaseException | None,
+        traceback: types.TracebackType | None,
+    ) -> bool | None:
+        """Raise any exception triggered within the runtime context."""
+        self.close()
+        return None

steam_editor_tools/version.py

@@ -0,0 +1,23 @@
+# -*- coding: UTF-8 -*-
+"""
+Version
+=======
+@ Steam Editor Tools
+
+Author
+------
+Yuchen Jin (cainmagi)
+cainmagi@gmail.com
+
+License
+-------
+MIT License
+
+Description
+-----------
+The version of this project.
+"""
+
+__all__ = ("__version__",)
+
+__version__ = "0.1.0"

steam_editor_tools-0.1.0.dist-info/METADATA

@@ -0,0 +1,219 @@
+Metadata-Version: 2.4
+Name: steam-editor-tools
+Version: 0.1.0
+Summary: This package offers editor tools helping users write Steam guides and reviews. Support Steam information queries, image editing tools, and BBCode text processing tools.
+Author-email: Yuchen Jin <cainmagi@gmail.com>
+Maintainer-email: Yuchen Jin <cainmagi@gmail.com>
+License: MIT License
+Project-URL: Homepage, https://github.com/cainmagi/steam-editor-tools
+Project-URL: Documentation, https://cainmagi.github.io/steam-editor-tools/
+Project-URL: Repository, https://github.com/cainmagi/steam-editor-tools.git
+Project-URL: Issues, https://github.com/cainmagi/steam-editor-tools/issues
+Project-URL: Changelog, https://github.com/cainmagi/steam-editor-tools/blob/main/Changelog.md
+Keywords: python,python3,python-library,image-processing,steam-api,steam-guide,steam-bbcode,steam-bbcode-converter,bbcode,markdown-to-bbcode,html-to-bbcode
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+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: Programming Language :: Python :: 3.14
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Framework :: Pydantic
+Classifier: Framework :: Pydantic :: 2
+Classifier: Topic :: Text Processing :: Markup
+Classifier: Topic :: Text Processing :: Markup :: HTML
+Classifier: Topic :: Text Processing :: Markup :: Markdown
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: typing-extensions>=4.1.0
+Requires-Dist: pydantic>=2
+Requires-Dist: markdown-it-py[linkify]
+Requires-Dist: beautifulsoup4
+Requires-Dist: pillow
+Requires-Dist: httpx
+Requires-Dist: rapidfuzz
+Provides-Extra: dev
+Requires-Dist: typing-extensions>=4.1.0; extra == "dev"
+Requires-Dist: black; extra == "dev"
+Requires-Dist: flake8; extra == "dev"
+Requires-Dist: flake8-black; extra == "dev"
+Requires-Dist: build; extra == "dev"
+Requires-Dist: wheel; extra == "dev"
+Provides-Extra: test
+Requires-Dist: pytest; extra == "test"
+Requires-Dist: pytest-base-url; extra == "test"
+Requires-Dist: pytest-html; extra == "test"
+Requires-Dist: pytest-metadata; extra == "test"
+Requires-Dist: py; extra == "test"
+Requires-Dist: pytest-variables; extra == "test"
+Requires-Dist: pytest-xdist; extra == "test"
+Requires-Dist: numpy; extra == "test"
+Requires-Dist: scikit-image; extra == "test"
+Dynamic: license-file
+
+# Steam Editor Tools: Help You Write Guides and Reviews
+
+<p><img alt="Banner" src="https://github.com/cainmagi/steam-editor-tools/blob/main/display/logo-banner.webp?raw=true"></p>
+
+<p align="center">
+  <a href="https://github.com/cainmagi/steam-editor-tools/releases/latest"><img alt="GitHub release (latest SemVer)" src="https://img.shields.io/github/v/release/cainmagi/steam-editor-tools?logo=github&sort=semver&style=flat-square"></a>
+  <a href="https://github.com/cainmagi/steam-editor-tools/releases"><img alt="GitHub all releases" src="https://img.shields.io/github/downloads/cainmagi/steam-editor-tools/total?logo=github&style=flat-square"></a>
+  <a href="https://github.com/cainmagi/steam-editor-tools/blob/main/LICENSE"><img alt="GitHub" src="https://img.shields.io/github/license/cainmagi/steam-editor-tools?style=flat-square&logo=opensourceinitiative&logoColor=white"></a>
+  <a href="https://pypi.org/project/steam-editor-tools"><img alt="PyPI - Downloads" src="https://img.shields.io/pypi/dm/steam-editor-tools?style=flat-square&logo=pypi&logoColor=white&label=pypi"/></a>
+</p>
+<p align="center">
+  <a href="https://github.com/cainmagi/steam-editor-tools/actions/workflows/python-package.yml"><img alt="GitHub Actions (Build)" src="https://img.shields.io/github/actions/workflow/status/cainmagi/steam-editor-tools/python-package.yml?style=flat-square&logo=githubactions&logoColor=white&label=build"></a>
+  <a href="https://github.com/cainmagi/steam-editor-tools/actions/workflows/python-publish.yml"><img alt="GitHub Actions (Release)" src="https://img.shields.io/github/actions/workflow/status/cainmagi/steam-editor-tools/python-publish.yml?style=flat-square&logo=githubactions&logoColor=white&label=release"></a>
+</p>
+
+This package offers editor tools helping users write Steam guides and reviews.
+
+This package supports:
+
+- Steam information queries
+- Image editing tools
+- BBCode text processing tools
+
+Users can write their documents with Markdown, use this package to process the images in the document, and convert the document to the Steam BBCode format.
+
+## 1. Install
+
+Intall the **latest released version** of this package by using the PyPI source:
+
+```sh
+python -m pip install steam-editor-tools
+```
+
+## 2. Usage
+
+The following minimal example shows a simple customization, where we convert a Markdown file into Steam BBCode, and print each header during the conversion.
+
+```python
+import os
+import steam_editor_tools as stet
+
+
+class CustomizedRenderer(stet.BBCodeRenderer):
+    def render_heading(self, node: stet.bbcode.nodes.HeadingNode) -> str:
+        print(self.render_children(node.children))
+        super().render_heading(node)
+        return super().render_heading(node)
+
+
+def convert(file_path: str) -> None:
+    out_file_path = os.path.splitext(file_path)[0].strip() + ".bbcode"
+    doc = stet.DocumentParser().parse_file(file_path)
+    with open(out_file_path, "w", encoding="utf-8") as fobj:
+        fobj.write(CustomizedRenderer().render(doc))
+
+
+convert("example.md")
+```
+
+Currently, we support the following features:
+
+### 2.1. Steam information query
+
+| Functionality         | Description                                                                                                                     |
+| :-------------------- | :------------------------------------------------------------------------------------------------------------------------------ |
+| Search app by name    | Given the partial name of an app (game), search for its information, including the ID. Support fuzzy searching.                 |
+| Get app details by ID | Given the app ID, fetch the full details, including the name, description, price, about page, and other information.            |
+| Download images       | Use methods such as `get_header_image()` to get the header image, background image, and official screenshots on the store page. |
+
+### 2.2. Image editing tools
+
+| Functionality       | Description                                                                                                                                |
+| :------------------ | :----------------------------------------------------------------------------------------------------------------------------------------- |
+| Image stack         | A code-based image editor, allowing users to stack multiple layers of images, texts, or LaTeX equations with styles.                       |
+| Image anchor        | Inspired by LaTeX's TikZ package, this package allows users to place images on the same canvas by using their relative positions.          |
+| Image optimization  | Users only need to specify the quality and the saving format. The package can choose the best way to optimize the saved image size.        |
+| Image modifications | Basic image modification tools such as image resizing, cropping and blurring.                                                              |
+| Thumbnail           | Provide an option to create Steam-compatible thumbnails. This feature is useful when users need to upload screenshots by themselves.       |
+| Batch processing    | Walk through a folder, apply a customized image processing function to each image, and save the results with thumbnails in another folder. |
+
+Actually, the title banner of this Readme file is created by the image editing tools. See the examples.
+
+> [!NOTE]
+> You need to have a locally installed LaTeX released version like [TeXLive][link-texlive] to use the equation features.
+
+### 2.3. BBCode text processing tools
+
+| Functionality       | Description                                                                                                                                                                       |
+| :------------------ | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Structured data     | All conversions are divided into two steps: Other formats -> `Document` stucture -> Steam BBCode. The intermediate `Document` strcture is supported by [pydantic][link-pydantic]. |
+| HTML to BBCode      | Recursively parse an HTML file, and convert it into `Document` or Steam BBCode.                                                                                                   |
+| Markdown to BBCode  | Use [markdown-it][link-markdown-it] to convert a Markdown file to HTML, then convert the HTML to `Document` or BBCode.                                                            |
+| Fetch a Steam guide | Given the URL of a Steam guide, convert it into `Document` or BBcode.                                                                                                             |
+
+## 3. Why using this package
+
+1. Compared to other BBCode conversion packages such as [html2bbcode][link-html2bbcode] and [html2phpbbcode][link-html2phpbbcode], our package strictly follows the current Steam BBCode format. Different forums may have different BBCode standards.
+2. Compared to [ihroteka-converter][link-ihroteka-converter], we fully support every format provided by Steam. Unlike that regular-expression-based conversion, the BBCode reconstruction in this package is based on a recursive analysis of the HTML structure. Therefore, our package will not omit any text as long as it appears in the original document.
+3. We offer flexibility of customization. Users can inject any rendering step of this package by simply overriding the methods of `steam_editor_tools.bbcode.BBCodeRenderer`. For example, we can customize a `BBCodeRenderer` to create a title image for each header.
+4. We offer convenient approaches for integrating the store page information into the output data. For example, users can easily convert a store page to BBCode if needed.
+
+## 4. Examples
+
+Currently, we offer the following examples in `./examples` folder:
+
+| Example                      | Description                                                                             |
+| :--------------------------- | :-------------------------------------------------------------------------------------- |
+| `markdown_to_bbcode`         | A minimal example converting Markdown to BBCode.                                        |
+| `save_description_of_a_game` | Save the "about the game" section of a Steam app as an HTML file.                       |
+| `download_screenshots`       | Download all official screenshots of a game and create thumbnails of them.              |
+| `download_a_guide`           | Fetch a Steam guide and save it as a BBCode file.                                       |
+| `create_a_title_figure`      | Customize a figure-based title. Such title images can be inserted into the Steam guide. |
+| `create_logo`                | Render the title bar of this readme file.                                               |
+
+The following two guides are written with the help of this tool. Check them for viewing the details:
+
+| Guide                           |                                    Link                                     |
+| :------------------------------ | :-------------------------------------------------------------------------: |
+| 此后，勇者学会了后验概率        | [:link:](https://steamcommunity.com/sharedfiles/filedetails/?id=3624295321) |
+| 《海猫鸣泣之时·出题篇》解（伪） | [:link:](https://steamcommunity.com/sharedfiles/filedetails/?id=2881849336) |
+
+## 5. Documentation
+
+> [!CAUTION]
+> This documentation is a work in progress. It should be ready when the package is tested to be stable.
+
+Check the documentation to find more details about the examples and APIs.
+
+https://cainmagi.github.io/steam-editor-tools/
+
+## 6. Contributing
+
+See [CONTRIBUTING.md :book:][link-contributing]
+
+## 7. Changelog
+
+See [Changelog.md :book:][link-changelog]
+
+## 8. Future plan
+
+- [x] HTML/Markdown to BBCode
+- [x] Multi-layer image synthesis
+- [x] Query Steam app ID by name
+- [x] Get Steam app details by ID
+- [x] Screenshot formatting
+- [ ] System/User font file detection
+- [ ] Image overlay with alpha channel
+- [ ] Image layer properties
+- [ ] Improved image anchor interfaces
+- [ ] More Steam queries based on public APIs
+
+[tool-git]: https://git-scm.com/downloads
+[link-contributing]: https://github.com/cainmagi/steam-editor-tools/blob/main/CONTRIBUTING.md
+[link-changelog]: https://github.com/cainmagi/steam-editor-tools/blob/main/Changelog.md
+[link-pydantic]: https://docs.pydantic.dev/
+[link-markdown-it]: https://markdown-it-py.readthedocs.io/
+[link-html2bbcode]: https://github.com/tengattack/html2bbcode.js
+[link-html2phpbbcode]: https://github.com/tdiam/html2phpbbcode
+[link-ihroteka-converter]: https://github.com/pivoshenko/ihroteka-converter/tree/main
+[link-texlive]: https://www.tug.org/texlive/

steam_editor_tools-0.1.0.dist-info/RECORD

@@ -0,0 +1,9 @@
+steam_editor_tools/__init__.py,sha256=PWqBDaKjv4EdUsiKcN4HNaocVxIz07cYvg6LwdIC4HY,1579
+steam_editor_tools/utils.py,sha256=bjtNREoZFIg9G-6AVirOB1qfarWr5_TmnLxq65Nun_0,3091
+steam_editor_tools/version.py,sha256=Mygnlo5R-Po6lRpkFV6wD8Zv4LaxHK7vlv8lJH9zkVY,259
+steam_editor_tools-0.1.0.dist-info/licenses/LICENSE,sha256=XLlJBnXelwpHmOYpjZIh-t7Kfq_yY4R6cZypUKhbb1s,1067
+steam_editor_tools-0.1.0.dist-info/METADATA,sha256=YRxjffvG9Eijkd_kfuJNv3mH_QR_ICAEXO_BMZcwRuA,13505
+steam_editor_tools-0.1.0.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+steam_editor_tools-0.1.0.dist-info/top_level.txt,sha256=Os5Q0olMW8Id8dt2fsINOX91GPBzQca7AEST9k8bG-c,19
+steam_editor_tools-0.1.0.dist-info/zip-safe,sha256=AbpHGcgLb-kRsJGnwFEktk7uzpZOCcBY74-YBdrKVGs,1
+steam_editor_tools-0.1.0.dist-info/RECORD,,

steam_editor_tools-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (80.9.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

steam_editor_tools-0.1.0.dist-info/licenses/LICENSE

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

steam_editor_tools-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+steam_editor_tools

steam_editor_tools-0.1.0.dist-info/zip-safe

@@ -0,0 +1 @@
+