symbolfyi 0.1.0__tar.gz

symbolfyi-0.1.0/.gitignore

@@ -0,0 +1,15 @@
+__pycache__/
+*.py[cod]
+*$py.class
+*.egg-info/
+dist/
+build/
+.eggs/
+*.egg
+.venv/
+venv/
+.mypy_cache/
+.ruff_cache/
+.pytest_cache/
+*.so
+.DS_Store

symbolfyi-0.1.0/LICENSE

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

symbolfyi-0.1.0/PKG-INFO

@@ -0,0 +1,123 @@
+Metadata-Version: 2.4
+Name: symbolfyi
+Version: 0.1.0
+Summary: Pure Python symbol & character encoding toolkit — 11 encoding formats, Unicode properties, HTML entities.
+Project-URL: Homepage, https://symbolfyi.com
+Project-URL: Documentation, https://symbolfyi.com/developers/
+Project-URL: Repository, https://github.com/fyipedia/symbolfyi
+Project-URL: Issues, https://github.com/fyipedia/symbolfyi/issues
+Author: FYIPedia
+License-Expression: MIT
+License-File: LICENSE
+Keywords: character,codepoint,encoding,html-entity,symbol,unicode,utf16,utf8
+Classifier: Development Status :: 4 - Beta
+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: Programming Language :: Python :: 3.14
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: Text Processing :: General
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Provides-Extra: full
+Requires-Dist: fonttools>=4.50; extra == 'full'
+Description-Content-Type: text/markdown
+
+# symbolfyi
+
+[![PyPI](https://img.shields.io/pypi/v/symbolfyi)](https://pypi.org/project/symbolfyi/)
+[![Python](https://img.shields.io/pypi/pyversions/symbolfyi)](https://pypi.org/project/symbolfyi/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
+
+Pure Python symbol & character encoding toolkit. Compute 11 encoding representations and full Unicode properties for any character. Includes 51 HTML entity mappings.
+
+> Look up any symbol at [symbolfyi.com](https://symbolfyi.com/)
+
+## Install
+
+```bash
+pip install symbolfyi              # Core (zero deps)
+pip install "symbolfyi[full]"      # + fonttools for Unicode block/script
+```
+
+## Quick Start
+
+```python
+from symbolfyi import get_encodings, get_info, lookup_html_entity
+
+# Encode any character (11 formats)
+enc = get_encodings("→")
+print(enc.unicode)        # U+2192
+print(enc.html_entity)    # →
+print(enc.css)            # \2192
+print(enc.javascript)     # \u{2192}
+print(enc.utf8_bytes)     # e2 86 92
+print(enc.url_encoded)    # %E2%86%92
+
+# Full Unicode properties (requires fonttools for block/script)
+info = get_info("♠")
+print(info.name)          # BLACK SPADE SUIT
+print(info.category_name) # Other Symbol
+print(info.block)         # Miscellaneous Symbols
+print(info.script)        # Common
+
+# HTML entity reverse lookup
+char = lookup_html_entity("♥")
+print(char)               # ♥
+```
+
+## API Reference
+
+### Core Functions
+
+| Function | Description |
+|----------|-------------|
+| `get_encodings(char) -> EncodingInfo` | Compute 11 encoding representations |
+| `get_info(char) -> SymbolInfo \| None` | Full Unicode properties + encodings |
+| `get_category_name(code) -> str` | Category code to human name |
+| `lookup_html_entity(entity) -> str \| None` | Entity string to character |
+
+### Data Types
+
+- **`EncodingInfo`** — 11-field NamedTuple: unicode, html_decimal, html_hex, html_entity, css, javascript, python, java, utf8_bytes, utf16_bytes, url_encoded
+- **`SymbolInfo`** — 12-field NamedTuple: codepoint, character, name, category, category_name, block, script, bidirectional, combining, mirrored, decomposition, encodings
+
+### Constants
+
+| Constant | Description |
+|----------|-------------|
+| `GENERAL_CATEGORIES` | 27 Unicode category codes with names |
+| `HTML_ENTITIES` | 51 codepoint-to-entity mappings |
+| `HTML_ENTITY_TO_CHAR` | 51 entity-to-character reverse mappings |
+
+## Features
+
+- **11 encoding types**: Unicode, HTML decimal/hex/entity, CSS, JavaScript, Python, Java, UTF-8/UTF-16 bytes, URL-encoded
+- **Unicode properties**: name, category, block, script, bidirectional, combining, mirrored, decomposition
+- **51 HTML entities**: Common entities with bidirectional lookup
+- **Zero required deps**: Core uses only stdlib (`unicodedata`, `urllib.parse`)
+- **Optional fonttools**: Install `symbolfyi[full]` for Unicode block and script info
+- **Type-safe**: Full type annotations, `py.typed` marker (PEP 561)
+
+## Related Packages
+
+| Package | Description |
+|---------|-------------|
+| [unicodefyi](https://github.com/fyipedia/unicodefyi) | Extended Unicode toolkit with 17 encodings + character search |
+| [colorfyi](https://github.com/fyipedia/colorfyi) | Color conversion, contrast, harmonies, shades |
+| [emojifyi](https://github.com/fyipedia/emojifyi) | Emoji encoding & metadata for 3,781 emojis |
+| [fontfyi](https://github.com/fyipedia/fontfyi) | Google Fonts metadata, CSS helpers, font pairings |
+
+## Links
+
+- [Symbol Browser](https://symbolfyi.com/) — Look up any symbol online
+- [API Documentation](https://symbolfyi.com/developers/) — REST API with free access
+- [Source Code](https://github.com/fyipedia/symbolfyi)
+
+## License
+
+MIT

symbolfyi-0.1.0/README.md

@@ -0,0 +1,94 @@
+# symbolfyi
+
+[![PyPI](https://img.shields.io/pypi/v/symbolfyi)](https://pypi.org/project/symbolfyi/)
+[![Python](https://img.shields.io/pypi/pyversions/symbolfyi)](https://pypi.org/project/symbolfyi/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
+
+Pure Python symbol & character encoding toolkit. Compute 11 encoding representations and full Unicode properties for any character. Includes 51 HTML entity mappings.
+
+> Look up any symbol at [symbolfyi.com](https://symbolfyi.com/)
+
+## Install
+
+```bash
+pip install symbolfyi              # Core (zero deps)
+pip install "symbolfyi[full]"      # + fonttools for Unicode block/script
+```
+
+## Quick Start
+
+```python
+from symbolfyi import get_encodings, get_info, lookup_html_entity
+
+# Encode any character (11 formats)
+enc = get_encodings("→")
+print(enc.unicode)        # U+2192
+print(enc.html_entity)    # →
+print(enc.css)            # \2192
+print(enc.javascript)     # \u{2192}
+print(enc.utf8_bytes)     # e2 86 92
+print(enc.url_encoded)    # %E2%86%92
+
+# Full Unicode properties (requires fonttools for block/script)
+info = get_info("♠")
+print(info.name)          # BLACK SPADE SUIT
+print(info.category_name) # Other Symbol
+print(info.block)         # Miscellaneous Symbols
+print(info.script)        # Common
+
+# HTML entity reverse lookup
+char = lookup_html_entity("♥")
+print(char)               # ♥
+```
+
+## API Reference
+
+### Core Functions
+
+| Function | Description |
+|----------|-------------|
+| `get_encodings(char) -> EncodingInfo` | Compute 11 encoding representations |
+| `get_info(char) -> SymbolInfo \| None` | Full Unicode properties + encodings |
+| `get_category_name(code) -> str` | Category code to human name |
+| `lookup_html_entity(entity) -> str \| None` | Entity string to character |
+
+### Data Types
+
+- **`EncodingInfo`** — 11-field NamedTuple: unicode, html_decimal, html_hex, html_entity, css, javascript, python, java, utf8_bytes, utf16_bytes, url_encoded
+- **`SymbolInfo`** — 12-field NamedTuple: codepoint, character, name, category, category_name, block, script, bidirectional, combining, mirrored, decomposition, encodings
+
+### Constants
+
+| Constant | Description |
+|----------|-------------|
+| `GENERAL_CATEGORIES` | 27 Unicode category codes with names |
+| `HTML_ENTITIES` | 51 codepoint-to-entity mappings |
+| `HTML_ENTITY_TO_CHAR` | 51 entity-to-character reverse mappings |
+
+## Features
+
+- **11 encoding types**: Unicode, HTML decimal/hex/entity, CSS, JavaScript, Python, Java, UTF-8/UTF-16 bytes, URL-encoded
+- **Unicode properties**: name, category, block, script, bidirectional, combining, mirrored, decomposition
+- **51 HTML entities**: Common entities with bidirectional lookup
+- **Zero required deps**: Core uses only stdlib (`unicodedata`, `urllib.parse`)
+- **Optional fonttools**: Install `symbolfyi[full]` for Unicode block and script info
+- **Type-safe**: Full type annotations, `py.typed` marker (PEP 561)
+
+## Related Packages
+
+| Package | Description |
+|---------|-------------|
+| [unicodefyi](https://github.com/fyipedia/unicodefyi) | Extended Unicode toolkit with 17 encodings + character search |
+| [colorfyi](https://github.com/fyipedia/colorfyi) | Color conversion, contrast, harmonies, shades |
+| [emojifyi](https://github.com/fyipedia/emojifyi) | Emoji encoding & metadata for 3,781 emojis |
+| [fontfyi](https://github.com/fyipedia/fontfyi) | Google Fonts metadata, CSS helpers, font pairings |
+
+## Links
+
+- [Symbol Browser](https://symbolfyi.com/) — Look up any symbol online
+- [API Documentation](https://symbolfyi.com/developers/) — REST API with free access
+- [Source Code](https://github.com/fyipedia/symbolfyi)
+
+## License
+
+MIT

symbolfyi-0.1.0/pyproject.toml

@@ -0,0 +1,64 @@
+[project]
+name = "symbolfyi"
+version = "0.1.0"
+description = "Pure Python symbol & character encoding toolkit — 11 encoding formats, Unicode properties, HTML entities."
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.10"
+authors = [{ name = "FYIPedia" }]
+keywords = ["unicode", "symbol", "encoding", "html-entity", "utf8", "utf16", "character", "codepoint"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Topic :: Text Processing :: General",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+    "Typing :: Typed",
+]
+dependencies = []
+
+[project.optional-dependencies]
+full = ["fonttools>=4.50"]
+
+[project.urls]
+Homepage = "https://symbolfyi.com"
+Documentation = "https://symbolfyi.com/developers/"
+Repository = "https://github.com/fyipedia/symbolfyi"
+Issues = "https://github.com/fyipedia/symbolfyi/issues"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/symbolfyi"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "-v --tb=short"
+
+[tool.ruff]
+target-version = "py310"
+line-length = 100
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B", "SIM", "RUF"]
+ignore = ["RUF022"]
+
+[tool.mypy]
+python_version = "3.10"
+strict = true
+
+[dependency-groups]
+dev = [
+    "fonttools>=4.50",
+    "mypy>=1.19.1",
+    "pytest>=9.0.2",
+    "ruff>=0.15.4",
+]

symbolfyi-0.1.0/src/symbolfyi/__init__.py

@@ -0,0 +1,58 @@
+"""symbolfyi — Pure Python symbol & character encoding toolkit.
+
+Compute 11 encoding representations (Unicode, HTML, CSS, JavaScript,
+Python, Java, UTF-8, UTF-16, URL) and Unicode properties for any character.
+Includes 47 HTML entity mappings.
+
+Zero required dependencies. Optional ``fonttools`` for block/script info.
+
+Usage::
+
+    from symbolfyi import get_encodings, get_info, lookup_html_entity
+
+    # Encode any character
+    enc = get_encodings("→")
+    print(enc.unicode)        # U+2192
+    print(enc.html_entity)    # →
+    print(enc.css)            # \\2192
+    print(enc.utf8_bytes)     # e2 86 92
+
+    # Full Unicode properties
+    info = get_info("♠")
+    print(info.name)          # BLACK SPADE SUIT
+    print(info.block)         # Miscellaneous Symbols (requires fonttools)
+    print(info.category_name) # Other Symbol
+
+    # HTML entity lookup
+    char = lookup_html_entity("♥")
+    print(char)               # ♥
+"""
+
+from symbolfyi.engine import (
+    GENERAL_CATEGORIES,
+    HTML_ENTITIES,
+    HTML_ENTITY_TO_CHAR,
+    EncodingInfo,
+    SymbolInfo,
+    get_category_name,
+    get_encodings,
+    get_info,
+    lookup_html_entity,
+)
+
+__version__ = "0.1.0"
+
+__all__ = [
+    # Data types
+    "EncodingInfo",
+    "SymbolInfo",
+    # Core functions
+    "get_encodings",
+    "get_info",
+    "get_category_name",
+    "lookup_html_entity",
+    # Data
+    "GENERAL_CATEGORIES",
+    "HTML_ENTITIES",
+    "HTML_ENTITY_TO_CHAR",
+]

symbolfyi-0.1.0/src/symbolfyi/engine.py

@@ -0,0 +1,256 @@
+"""Symbol encoding and Unicode property engine — stateless, <1ms per call.
+
+Computes 11 encoding representations and Unicode properties for any character.
+Uses stdlib ``unicodedata`` for core properties; ``fontTools`` (optional) for
+Unicode block and script data.
+
+Zero required dependencies. Install ``fonttools`` for block/script info::
+
+    pip install symbolfyi[full]
+"""
+
+from __future__ import annotations
+
+import unicodedata
+from typing import NamedTuple
+from urllib.parse import quote
+
+# Try fontTools for block/script (optional dependency)
+try:
+    from fontTools.unicodedata import block as ft_block
+    from fontTools.unicodedata import script as ft_script
+
+    _HAS_FONTTOOLS = True
+except ImportError:
+    _HAS_FONTTOOLS = False
+
+
+# ─── Unicode general category names ──────────────────────────────────────────
+
+GENERAL_CATEGORIES: dict[str, str] = {
+    "Lu": "Uppercase Letter",
+    "Ll": "Lowercase Letter",
+    "Lt": "Titlecase Letter",
+    "Lm": "Modifier Letter",
+    "Lo": "Other Letter",
+    "Mn": "Nonspacing Mark",
+    "Mc": "Spacing Mark",
+    "Me": "Enclosing Mark",
+    "Nd": "Decimal Number",
+    "Nl": "Letter Number",
+    "No": "Other Number",
+    "Pc": "Connector Punctuation",
+    "Pd": "Dash Punctuation",
+    "Ps": "Open Punctuation",
+    "Pe": "Close Punctuation",
+    "Pi": "Initial Punctuation",
+    "Pf": "Final Punctuation",
+    "Po": "Other Punctuation",
+    "Sm": "Math Symbol",
+    "Sc": "Currency Symbol",
+    "Sk": "Modifier Symbol",
+    "So": "Other Symbol",
+    "Zs": "Space Separator",
+    "Zl": "Line Separator",
+    "Zp": "Paragraph Separator",
+    "Cc": "Control",
+    "Cf": "Format",
+}
+
+
+# ─── HTML entity mappings ────────────────────────────────────────────────────
+
+HTML_ENTITIES: dict[int, str] = {
+    0x0026: "&amp;",
+    0x003C: "&lt;",
+    0x003E: "&gt;",
+    0x0022: "&quot;",
+    0x00A9: "&copy;",
+    0x00AE: "&reg;",
+    0x2122: "&trade;",
+    0x00A3: "&pound;",
+    0x00A5: "&yen;",
+    0x20AC: "&euro;",
+    0x00B0: "&deg;",
+    0x00B1: "&plusmn;",
+    0x00D7: "&times;",
+    0x00F7: "&divide;",
+    0x2190: "&larr;",
+    0x2191: "&uarr;",
+    0x2192: "&rarr;",
+    0x2193: "&darr;",
+    0x2194: "&harr;",
+    0x21D0: "&lArr;",
+    0x21D2: "&rArr;",
+    0x21D4: "&hArr;",
+    0x2200: "&forall;",
+    0x2202: "&part;",
+    0x2203: "&exist;",
+    0x2205: "&empty;",
+    0x2207: "&nabla;",
+    0x2208: "&isin;",
+    0x2209: "&notin;",
+    0x220B: "&ni;",
+    0x220F: "&prod;",
+    0x2211: "&sum;",
+    0x221A: "&radic;",
+    0x221E: "&infin;",
+    0x2227: "&and;",
+    0x2228: "&or;",
+    0x2229: "&cap;",
+    0x222A: "&cup;",
+    0x222B: "&int;",
+    0x2260: "&ne;",
+    0x2264: "&le;",
+    0x2265: "&ge;",
+    0x2282: "&sub;",
+    0x2283: "&sup;",
+    0x2286: "&sube;",
+    0x2287: "&supe;",
+    0x25CA: "&loz;",
+    0x2660: "&spades;",
+    0x2663: "&clubs;",
+    0x2665: "&hearts;",
+    0x2666: "&diams;",
+}
+
+# Reverse mapping: entity string → character
+HTML_ENTITY_TO_CHAR: dict[str, str] = {v: chr(k) for k, v in HTML_ENTITIES.items()}
+
+
+# ─── Data types ──────────────────────────────────────────────────────────────
+
+
+class EncodingInfo(NamedTuple):
+    """11 encoding representations for a character."""
+
+    unicode: str
+    html_decimal: str
+    html_hex: str
+    html_entity: str
+    css: str
+    javascript: str
+    python: str
+    java: str
+    utf8_bytes: str
+    utf16_bytes: str
+    url_encoded: str
+
+
+class SymbolInfo(NamedTuple):
+    """Full Unicode properties + encodings for a character."""
+
+    codepoint: int
+    character: str
+    name: str
+    category: str
+    category_name: str
+    block: str
+    script: str
+    bidirectional: str
+    combining: int
+    mirrored: bool
+    decomposition: str
+    encodings: EncodingInfo
+
+
+# ─── Core functions ──────────────────────────────────────────────────────────
+
+
+def get_encodings(char: str) -> EncodingInfo:
+    """Compute 11 encoding representations for a single character.
+
+    >>> enc = get_encodings("♠")
+    >>> enc.unicode
+    'U+2660'
+    >>> enc.html_entity
+    '&spades;'
+    >>> enc.utf8_bytes
+    'e2 99 a0'
+    """
+    cp = ord(char)
+    if cp <= 0xFFFF:
+        python_repr = f"\\u{cp:04x}"
+        java_repr = f"\\u{cp:04X}"
+    else:
+        python_repr = f"\\U{cp:08x}"
+        high = 0xD800 + ((cp - 0x10000) >> 10)
+        low = 0xDC00 + ((cp - 0x10000) & 0x3FF)
+        java_repr = f"\\u{high:04X}\\u{low:04X}"
+
+    return EncodingInfo(
+        unicode=f"U+{cp:04X}",
+        html_decimal=f"&#{cp};",
+        html_hex=f"&#x{cp:X};",
+        html_entity=HTML_ENTITIES.get(cp, ""),
+        css=f"\\{cp:04X}",
+        javascript=f"\\u{{{cp:X}}}",
+        python=python_repr,
+        java=java_repr,
+        utf8_bytes=char.encode("utf-8").hex(" "),
+        utf16_bytes=char.encode("utf-16-be").hex(" "),
+        url_encoded=quote(char),
+    )
+
+
+def get_info(char: str) -> SymbolInfo | None:
+    """Get full Unicode properties and encodings for a character.
+
+    Returns ``None`` if the character has no Unicode name (control chars, etc.).
+
+    >>> info = get_info("→")
+    >>> info.name if info else None
+    'RIGHTWARDS ARROW'
+    >>> info.block if info else None  # requires fonttools
+    'Arrows'
+    """
+    try:
+        cp = ord(char)
+        name = unicodedata.name(char, None)
+        if name is None:
+            return None
+        cat = unicodedata.category(char)
+
+        if _HAS_FONTTOOLS:
+            block = ft_block(cp)
+            script = ft_script(cp)
+        else:
+            block = ""
+            script = ""
+
+        return SymbolInfo(
+            codepoint=cp,
+            character=char,
+            name=name,
+            category=cat,
+            category_name=GENERAL_CATEGORIES.get(cat, cat),
+            block=block,
+            script=script,
+            bidirectional=unicodedata.bidirectional(char),
+            combining=unicodedata.combining(char),
+            mirrored=bool(unicodedata.mirrored(char)),
+            decomposition=unicodedata.decomposition(char),
+            encodings=get_encodings(char),
+        )
+    except (ValueError, OverflowError):
+        return None
+
+
+def get_category_name(category_code: str) -> str:
+    """Get the full name for a Unicode general category code.
+
+    >>> get_category_name("Sm")
+    'Math Symbol'
+    """
+    return GENERAL_CATEGORIES.get(category_code, category_code)
+
+
+def lookup_html_entity(entity: str) -> str | None:
+    """Look up the character for an HTML entity string.
+
+    >>> lookup_html_entity("&amp;")
+    '&'
+    >>> lookup_html_entity("&hearts;")
+    '♥'
+    """
+    return HTML_ENTITY_TO_CHAR.get(entity)