storypy 0.4.2__tar.gz

storypy-0.4.2/.gitattributes

@@ -0,0 +1,29 @@
+[^.]*.* linguist-detectable=true linguist-generated=false linguist-vendored=false linguist-documentation=false
+.* linguist-detectable=false
+*.rst linguist-detectable=false
+*.css linguist-detectable=false
+
+# Source files
+*.pxd    text diff=python
+*.py     text diff=python
+*.py3    text diff=python
+*.pyw    text diff=python
+*.pyx    text diff=python
+*.pyz    text diff=python
+*.pyi    text diff=python
+
+# Binary files
+*.db     binary
+*.p      binary
+*.pkl    binary
+*.pickle binary
+*.pyc    binary export-ignore
+*.pyo    binary export-ignore
+*.pyd    binary
+
+# Jupyter notebook
+*.ipynb  text eol=lf
+
+# Static files in documentation
+*.png    binary
+*.psd    binary

storypy-0.4.2/.gitignore

@@ -0,0 +1,216 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[codz]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#   Usually these files are written by a python script from a template
+#   before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py.cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+# .python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+# Pipfile.lock
+
+# UV
+#   Similar to Pipfile.lock, it is generally recommended to include uv.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+# uv.lock
+
+# poetry
+#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
+# poetry.lock
+# poetry.toml
+
+# pdm
+#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
+#   pdm recommends including project-wide configuration in pdm.toml, but excluding .pdm-python.
+#   https://pdm-project.org/en/latest/usage/project/#working-with-version-control
+# pdm.lock
+# pdm.toml
+.pdm-python
+.pdm-build/
+
+# pixi
+#   Similar to Pipfile.lock, it is generally recommended to include pixi.lock in version control.
+# pixi.lock
+#   Pixi creates a virtual environment in the .pixi directory, just like venv module creates one
+#   in the .venv directory. It is recommended not to include this directory in version control.
+.pixi
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# Redis
+*.rdb
+*.aof
+*.pid
+
+# RabbitMQ
+mnesia/
+rabbitmq/
+rabbitmq-data/
+
+# ActiveMQ
+activemq-data/
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.envrc
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# PyCharm
+#   JetBrains specific template is maintained in a separate JetBrains.gitignore that can
+#   be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
+#   and can be added to the global gitignore or merged into this file.  For a more nuclear
+#   option (not recommended) you can uncomment the following to ignore the entire idea folder.
+# .idea/
+
+# Abstra
+#   Abstra is an AI-powered process automation framework.
+#   Ignore directories containing user credentials, local state, and settings.
+#   Learn more at https://abstra.io/docs
+.abstra/
+
+# Visual Studio Code
+#   Visual Studio Code specific template is maintained in a separate VisualStudioCode.gitignore 
+#   that can be found at https://github.com/github/gitignore/blob/main/Global/VisualStudioCode.gitignore
+#   and can be added to the global gitignore or merged into this file. However, if you prefer, 
+#   you could uncomment the following to ignore the entire vscode folder
+# .vscode/
+
+# Ruff stuff:
+.ruff_cache/
+
+# PyPI configuration file
+.pypirc
+
+# Marimo
+marimo/_static/
+marimo/_lsp/
+__marimo__/
+
+# Streamlit
+.streamlit/secrets.toml

storypy-0.4.2/.readthedocs.yml

@@ -0,0 +1,18 @@
+# Read the Docs configuration file
+# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
+
+version: 2
+
+build:
+  os: ubuntu-24.04
+  tools:
+    python: "3.13"
+
+# Build documentation in the "docs/" directory with Sphinx
+sphinx:
+   configuration: docs/source/conf.py
+
+# See https://docs.readthedocs.io/en/stable/guides/reproducible-builds.html
+python:
+  install:
+    - requirements: docs/requirements.txt

storypy-0.4.2/LICENSE

@@ -0,0 +1,19 @@
+Copyright (c) 2026 Andras Baki
+
+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.

storypy-0.4.2/PKG-INFO

@@ -0,0 +1,22 @@
+Metadata-Version: 2.4
+Name: storypy
+Version: 0.4.2
+Summary: A Python module for metaprogramming
+Project-URL: Homepage, https://github.com/storypy/storypy
+Project-URL: Issues, https://github.com/storypy/storypy/issues
+Author-email: Andras Baki <andrasbaki6@googlemail.com>
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Requires-Python: >=3.9
+Description-Content-Type: text/x-rst
+
+StoryPy
+=======
+
+StoryPy is a Python module for metaprogramming.
+
+----
+
+Copyright (c) 2026 Andras Baki

storypy-0.4.2/README.rst

@@ -0,0 +1,8 @@
+StoryPy
+=======
+
+StoryPy is a Python module for metaprogramming.
+
+----
+
+Copyright (c) 2026 Andras Baki

storypy-0.4.2/docs/Makefile

@@ -0,0 +1,20 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line, and also
+# from the environment for the first two.
+SPHINXOPTS    ?=
+SPHINXBUILD   ?= sphinx-build
+SOURCEDIR     = source
+BUILDDIR      = build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

storypy-0.4.2/docs/make.bat

@@ -0,0 +1,35 @@
+@ECHO OFF
+
+pushd %~dp0
+
+REM Command file for Sphinx documentation
+
+if "%SPHINXBUILD%" == "" (
+	set SPHINXBUILD=sphinx-build
+)
+set SOURCEDIR=source
+set BUILDDIR=build
+
+%SPHINXBUILD% >NUL 2>NUL
+if errorlevel 9009 (
+	echo.
+	echo.The 'sphinx-build' command was not found. Make sure you have Sphinx
+	echo.installed, then set the SPHINXBUILD environment variable to point
+	echo.to the full path of the 'sphinx-build' executable. Alternatively you
+	echo.may add the Sphinx directory to PATH.
+	echo.
+	echo.If you don't have Sphinx installed, grab it from
+	echo.https://www.sphinx-doc.org/
+	exit /b 1
+)
+
+if "%1" == "" goto help
+
+%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+goto end
+
+:help
+%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+
+:end
+popd

storypy-0.4.2/docs/requirements.txt

@@ -0,0 +1,2 @@
+furo
+sphinx-notfound-page

storypy-0.4.2/docs/source/_autosummary/storypy.main.rst

@@ -0,0 +1,18 @@
+storypy.main
+============
+
+.. automodule:: storypy.main
+
+   
+   .. rubric:: Functions
+
+   .. autosummary::
+   
+      declare
+   
+   .. rubric:: Classes
+
+   .. autosummary::
+   
+      StoryPy_Core
+   

storypy-0.4.2/docs/source/_autosummary/storypy.rst

@@ -0,0 +1,13 @@
+storypy
+=======
+
+.. automodule:: storypy
+
+   
+.. rubric:: Modules
+
+.. autosummary::
+   :toctree:
+   :recursive:
+
+   main

storypy-0.4.2/docs/source/_static/stylesheet.css

@@ -0,0 +1,4 @@
+a {
+  color: #5ca5ff;
+}
+

storypy-0.4.2/docs/source/branding.rst

@@ -0,0 +1,19 @@
+Brand resources
+===============
+
+StoryPy logo
+------------
+
+The StoryPy logo is available in PNG and Photoshop formats.
+
+Download links: `PNG <_static/logo.png>`__ `PSD <_static/logo.psd>`__
+
+Legal
+^^^^^
+
+The StoryPy logo is the exclusive property of Andras Baki and the StoryPy project. Unauthorized use, reproduction, distribution, or modification of the StoryPy logo without prior written permission from StoryPy is strictly prohibited.
+
+For permission, contact `andrasbaki6+storypy@googlemail.com <mailto:andrasbaki6+storypy@googlemail.com>`__.
+
+Copyright (c) The StoryPy logo 2026 Andras Baki
+

storypy-0.4.2/docs/source/conf.py

@@ -0,0 +1,50 @@
+# Configuration file for the Sphinx documentation builder.
+#
+# For the full list of built-in configuration values, see the documentation:
+# https://www.sphinx-doc.org/en/master/usage/configuration.html
+
+# -- Project information -----------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
+
+import os
+import sys
+sys.path.insert(0, os.path.abspath('../../src'))
+
+project = 'StoryPy'
+copyright = '2026, Andras Baki'
+author = 'Andras Baki'
+release = '0.4.2'
+
+# -- General configuration ---------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
+
+extensions = [
+    'sphinx.ext.autodoc',
+    'sphinx.ext.viewcode',
+    'sphinx.ext.autosummary',
+    'sphinx.ext.napoleon',
+    'notfound.extension',
+]
+
+autosummary_generate = True
+autoclass_content = "both"
+
+templates_path = ['_templates']
+exclude_patterns = []
+
+# -- Options for HTML output -------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
+
+html_theme = 'furo'
+html_static_path = ['_static']
+html_logo = "_static/logo.png"
+html_css_files = [
+    'stylesheet.css',
+]
+html_context = {
+    "github_user": "storypy",
+    "github_repo": "storypy",
+    "github_version": "main",
+    "doc_path": "docs",
+}
+

storypy-0.4.2/docs/source/guides.rst

@@ -0,0 +1,39 @@
+Using StoryPy
+=============
+
+First of all, to use the StoryPy module in your project, you need to include it::
+
+    import StoryPy
+
+After the module is included, all its objects will be available.
+
+The ``declare`` function
+------------------------
+
+You can use the ``StoryPy.declare()`` function to declare variables in the main scope of your program (scope selection is not yet supported, but planned).
+
+    Note that if the specified entity already exists in the main scope, the ``declare`` function will override it without confirmation.
+
+Usage
+^^^^^
+
+The ``declare`` function needs three inputs: ``category``, ``name``, and ``value``, as shown below::
+
+    StoryPy.declare(category: str, name: str, value: Any)
+
+The ``category`` input specifies the category of the entity you are declaring (e.g. "variable", "function"). Must be a string.
+
+    For now, only the "variable" category can be entered, meaning you can only declare variables with the ``declare`` function. Other categories are planned to be added in the future.
+
+The ``name`` input specifies the name of the entity you are declaring. If the "variable" category is set, this will be the name of the created variable. Must be a string.
+
+The ``value`` input specifies the value of the entity you are declaring. If the "variable" category is set, this will be the value of the created variable. Can have any type.
+
+Examples
+^^^^^^^^
+
+So we'd like to create a variable called "one", with the integer value of 1. We can do this by running::
+
+    StoryPy.declare("variable", "one", 1)
+
+And that's it. Now, the ``one`` variable will be available in our program's main scope.

storypy-0.4.2/docs/source/index.rst

@@ -0,0 +1,23 @@
+.. StoryPy documentation master file.
+
+.. meta::
+   :description: StoryPy is a Python module for metaprogramming.
+   :keywords: StoryPy, Python, metaprogramming, programming
+
+StoryPy documentation
+=====================
+
+StoryPy is a Python module for metaprogramming.
+
+This documentation provides the following:
+
+* guides for using StoryPy in your project
+* source code documentation (autogenerated)
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Contents:
+
+   installation
+   guides
+   modules

storypy-0.4.2/docs/source/installation.rst

@@ -0,0 +1,2 @@
+Installing StoryPy
+==================

storypy-0.4.2/docs/source/modules.rst

@@ -0,0 +1,8 @@
+Source code docs
+================
+
+.. autosummary::
+   :toctree: _autosummary
+   :recursive:
+
+   storypy

storypy-0.4.2/pyproject.toml

@@ -0,0 +1,24 @@
+[project]
+name = "storypy"
+version = "0.4.2"
+authors = [
+  { name="Andras Baki", email="andrasbaki6@googlemail.com" },
+]
+description = "A Python module for metaprogramming"
+readme = "README.rst"
+requires-python = ">=3.9"
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "Operating System :: OS Independent",
+]
+license = "MIT"
+license-files = ["LICENSE"]
+
+[project.urls]
+Homepage = "https://github.com/storypy/storypy"
+Issues = "https://github.com/storypy/storypy/issues"
+
+[build-system]
+requires = ["hatchling >= 1.26"]
+build-backend = "hatchling.build"
+

storypy-0.4.2/src/.gitkeep

@@ -0,0 +1 @@
+gitkeep

storypy-0.4.2/src/storypy/__init__.py

@@ -0,0 +1,4 @@
+from .main import StoryPy_Core, declare
+
+__all__ = ["StoryPy_Core", "declare"]
+

storypy-0.4.2/src/storypy/main.py

@@ -0,0 +1,57 @@
+#!/usr/bin/python3
+
+import keyword
+import sys
+from typing import Any, Literal
+
+class StoryPy_Core:
+    @staticmethod
+    def declare(category: Literal["variable"], name: str, value: Any) -> None:
+        """
+        Declare a new entity inside the caller's global namespace.
+
+        Currently only ``"variable"`` declarations are supported.
+
+        Args:
+            category (Literal["variable"]):
+                The type of entity to declare.
+            name (str):
+                The name of the variable to create.
+            value (Any):
+                The value assigned to the declared variable.
+
+        Raises:
+            SyntaxError:
+                If ``name`` is not a valid Python identifier or is a reserved keyword.
+            ValueError:
+                If an unsupported ``category`` is provided.
+
+        Example:
+            >>> StoryPy_Core.declare("variable", "x", 42)
+            >>> x
+            42
+
+        See Also:
+            :mod:`sys`
+            :func:`keyword.iskeyword`
+        """
+        if category.strip().lower() == "variable":
+            global valid
+            valid = lambda s: s.isidentifier() and not keyword.iskeyword(s) and all(c.isascii() for c in s)
+
+            if valid(name):
+                _caller = sys.modules["__main__"]
+                _caller.__dict__[name] = value
+            
+            else:
+                raise SyntaxError(f"Illegal variable name {name}")
+            
+        else:
+            raise ValueError(f"Unrecognized category {category}")
+
+declare = StoryPy_Core.declare
+
+if __name__ == "__main__":
+    print("The StoryPy module is not intended to be run standalone.")
+    print("Try importing StoryPy in your project.")
+

storypy-0.4.2/tests/.gitkeep

@@ -0,0 +1 @@
+gitkeep