pyinterfaces 0.0.1__tar.gz → 0.2.0__tar.gz

pyinterfaces-0.2.0/PKG-INFO

@@ -0,0 +1,117 @@
+Metadata-Version: 2.4
+Name: pyinterfaces
+Version: 0.2.0
+Summary: Interface in POO with Python
+License-Expression: MIT
+License-File: license.txt
+Keywords: interface,java,syntax,brunozolotareff,pyinterfaces
+Author: Bruno Zolotareff
+Author-email: brunozolotareff@gmail.com
+Requires-Python: >=3.10
+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
+Description-Content-Type: text/markdown
+
+# pyinterfaces
+
+A lightweight Python compiler extension that brings clean, Java-style interface syntax to Python using native braces `{}`.
+
+[![PyPI version](https://shields.io)](https://pypi.org)
+[![Python Versions](https://shields.io)](https://pypi.org)
+
+---
+
+## 📐 Why pyinterfaces? (Software Engineering Perspective)
+
+In modern **Software Engineering**, separating *definition* from *implementation* is a core architectural principle. 
+Following SOLID principles—specifically the **Interface Segregation Principle (ISP)** and the **Dependency Inversion Principle (DIP)**—software components should depend on abstractions (interfaces), not on concrete logic.
+
+While standard Python uses `abc.ABC` and `@abstractmethod` to enforce contracts, the syntax can often look cluttered, repetitive, and conceptually muddy (as Python abstract classes can accidentally mix actual logic with abstract models).
+
+**`pyinterfaces`** bridges this gap by enforcing **Pure Interfaces**. It allows software engineers to declare strict structural contracts using the familiar, elegant, and universally understood Java/C# layout, keeping your architecture clean and highly readable.
+
+---
+
+## ✨ Features
+
+- **Java-Style Syntax**: Declare structures using `Interface Name { ... }`.
+- **Pure Abstraction**: No mixed implementation code allowed inside the contract block.
+- **Runtime Enforcement**: Automatically triggers native Python `abc` validations under the hood.
+- **Zero Overhead**: Translated seamlessly during file tokenization using custom stream decoding.
+
+---
+
+## 🚀 Installation
+
+You can install `pyinterfaces` via `pip` or add it to your project using `poetry`:
+
+```bash
+pip install pyinterfaces
+```
+
+Or with Poetry:
+```bash
+poetry add pyinterfaces
+```
+
+---
+
+## 💻 Usage
+
+To enable the custom Java-like syntax parsing, you **must** include the magic encoding comment `# -*- coding: java_interface -*-` at the very first line of your Python script.
+
+Here is a standard example of designing a decoupled Payment System:
+
+```python
+# -*- coding: java_interface -*-
+import pyinterfaces
+
+# 1. Define the pure architectural contract
+Interface PaymentProcessor {
+    process_payment(self, amount: float) -> bool
+    refund_payment(self, transaction_id: str) -> None
+}
+
+# 2. Implement the contract in standard Python classes
+class PixProcessor(PaymentProcessor):
+    def process_payment(self, amount: float) -> bool:
+        print(f"Processing R\${amount} instantly via Pix.")
+        return True
+
+    def refund_payment(self, transaction_id: str) -> None:
+        print(f"Refunding transaction {transaction_id}.")
+
+# 3. Compile-time / Runtime validation
+class BrokenProcessor(PaymentProcessor):
+    def process_payment(self, amount: float) -> bool:
+        return True
+    # ERROR! Missing 'refund_payment' method implementation.
+```
+
+If a developer attempts to instantiate `BrokenProcessor`, Python will instantly raise a `TypeError`, stating that the class failed to implement the strict contract requirements defined by your interface.
+
+---
+
+## 🛠️ How it works under the hood
+
+`pyinterfaces` hooks directly into Python's native `codecs` registry. When the interpretator reads the `# -*- coding: java_interface -*-` header, it streams your file through our custom pre-processor, safely transforming the custom block syntax into fully valid standard Python `abc.ABC` structures before the code even executes.
+
+---
+
+## 👤 Author
+
+- Created and maintained by **Bruno Zolotareff**
+- PyPI Repository: [https://pypi.org](https://pypi.org)
+
+## 🤝 Acknowledgments
+
+Special thanks to my friend **Leandro Reginaldo** for collaborating on the original concept, brainstorming the architectural ideas, and helping to shape the vision of `pyinterfaces`. This project wouldn't be the same without your insights!
+
+
+## 📄 License
+
+This project is licensed under the MIT License.

pyinterfaces-0.2.0/README.md

@@ -0,0 +1,99 @@
+# pyinterfaces
+
+A lightweight Python compiler extension that brings clean, Java-style interface syntax to Python using native braces `{}`.
+
+[![PyPI version](https://shields.io)](https://pypi.org)
+[![Python Versions](https://shields.io)](https://pypi.org)
+
+---
+
+## 📐 Why pyinterfaces? (Software Engineering Perspective)
+
+In modern **Software Engineering**, separating *definition* from *implementation* is a core architectural principle. 
+Following SOLID principles—specifically the **Interface Segregation Principle (ISP)** and the **Dependency Inversion Principle (DIP)**—software components should depend on abstractions (interfaces), not on concrete logic.
+
+While standard Python uses `abc.ABC` and `@abstractmethod` to enforce contracts, the syntax can often look cluttered, repetitive, and conceptually muddy (as Python abstract classes can accidentally mix actual logic with abstract models).
+
+**`pyinterfaces`** bridges this gap by enforcing **Pure Interfaces**. It allows software engineers to declare strict structural contracts using the familiar, elegant, and universally understood Java/C# layout, keeping your architecture clean and highly readable.
+
+---
+
+## ✨ Features
+
+- **Java-Style Syntax**: Declare structures using `Interface Name { ... }`.
+- **Pure Abstraction**: No mixed implementation code allowed inside the contract block.
+- **Runtime Enforcement**: Automatically triggers native Python `abc` validations under the hood.
+- **Zero Overhead**: Translated seamlessly during file tokenization using custom stream decoding.
+
+---
+
+## 🚀 Installation
+
+You can install `pyinterfaces` via `pip` or add it to your project using `poetry`:
+
+```bash
+pip install pyinterfaces
+```
+
+Or with Poetry:
+```bash
+poetry add pyinterfaces
+```
+
+---
+
+## 💻 Usage
+
+To enable the custom Java-like syntax parsing, you **must** include the magic encoding comment `# -*- coding: java_interface -*-` at the very first line of your Python script.
+
+Here is a standard example of designing a decoupled Payment System:
+
+```python
+# -*- coding: java_interface -*-
+import pyinterfaces
+
+# 1. Define the pure architectural contract
+Interface PaymentProcessor {
+    process_payment(self, amount: float) -> bool
+    refund_payment(self, transaction_id: str) -> None
+}
+
+# 2. Implement the contract in standard Python classes
+class PixProcessor(PaymentProcessor):
+    def process_payment(self, amount: float) -> bool:
+        print(f"Processing R\${amount} instantly via Pix.")
+        return True
+
+    def refund_payment(self, transaction_id: str) -> None:
+        print(f"Refunding transaction {transaction_id}.")
+
+# 3. Compile-time / Runtime validation
+class BrokenProcessor(PaymentProcessor):
+    def process_payment(self, amount: float) -> bool:
+        return True
+    # ERROR! Missing 'refund_payment' method implementation.
+```
+
+If a developer attempts to instantiate `BrokenProcessor`, Python will instantly raise a `TypeError`, stating that the class failed to implement the strict contract requirements defined by your interface.
+
+---
+
+## 🛠️ How it works under the hood
+
+`pyinterfaces` hooks directly into Python's native `codecs` registry. When the interpretator reads the `# -*- coding: java_interface -*-` header, it streams your file through our custom pre-processor, safely transforming the custom block syntax into fully valid standard Python `abc.ABC` structures before the code even executes.
+
+---
+
+## 👤 Author
+
+- Created and maintained by **Bruno Zolotareff**
+- PyPI Repository: [https://pypi.org](https://pypi.org)
+
+## 🤝 Acknowledgments
+
+Special thanks to my friend **Leandro Reginaldo** for collaborating on the original concept, brainstorming the architectural ideas, and helping to shape the vision of `pyinterfaces`. This project wouldn't be the same without your insights!
+
+
+## 📄 License
+
+This project is licensed under the MIT License.

pyinterfaces-0.2.0/license.txt

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

pyinterfaces-0.2.0/pyinterfaces/__init__.py

@@ -0,0 +1,12 @@
+"""
+pyinterfaces - Java-style interfaces for Python.
+
+Co-conceptualized and inspired by Leandro Reginaldo.
+Maintained by Bruno Zolotareff.
+"""
+
+
+from .compilador import registrar_syntax
+
+# Ativa o mecanismo de codec assim que a biblioteca é importada
+registrar_syntax()

pyinterfaces-0.2.0/pyinterfaces/compilador.py

@@ -0,0 +1,116 @@
+import codecs
+import io
+import re
+
+def converter_tipos_java_para_python(argumentos_str: str) -> str:
+    """
+    Transforma 'String titular, int idade' em 'titular: str, idade: int'.
+    Também garante que o 'self' seja mantido corretamente se o usuário colocar.
+    """
+    mapa_tipos = {
+        'String': 'str',
+        'int': 'int',
+        'double': 'float',
+        'float': 'float',
+        'boolean': 'bool',
+        'void': 'None',
+        'List': 'list',
+        'Map': 'dict'
+    }
+    
+    argumentos_limpos = argumentos_str.strip()
+    if not argumentos_limpos:
+        return "self"
+        
+    partes = [p.strip() for p in argumentos_limpos.split(',')]
+    novos_args = []
+    
+    # CORREÇÃO AQUI: Verificamos se 'self' está contido na lista de partes
+    if len(partes) > 0 and partes[0] == 'self':
+        novos_args.append('self')
+        partes = partes[1:]
+    else:
+        # Injeta o 'self' automaticamente (padrão Java puro)
+        novos_args.append('self')
+        
+    for parte in partes:
+        if not parte:
+            continue
+        componentes = re.split(r'\s+', parte)
+        if len(componentes) == 2:
+            tipo_java, nome_var = componentes
+            tipo_python = mapa_tipos.get(tipo_java, tipo_java)
+            novos_args.append(f"{nome_var}: {tipo_python}")
+        else:
+            novos_args.append(parte)
+            
+    return ", ".join(novos_args)
+
+def traduzir_sintaxe_java(texto: str) -> str:
+    """
+    Varre o arquivo de texto substituindo a sintaxe 'Interface Nome { ... }'
+    por classes Python puras usando abc.ABC, tipagem estrita e @abstractmethod.
+    """
+    linhas = texto.split('\n')
+    resultado = ["from abc import ABC, abstractmethod\n"]
+    dentro_da_interface = False
+    
+    for linha in linhas:
+        # 1. Detecta o início da declaração: 'Interface Nome {'
+        inicio_match = re.match(r'\s*Interface\s+(\w+)\s*\{', linha)
+        if inicio_match:
+            nome_interface = inicio_match.group(1)
+            resultado.append(f"class {nome_interface}(ABC):")
+            dentro_da_interface = True
+            continue
+            
+        if dentro_da_interface:
+            # 2. Detecta o fechamento da interface com a chave '}'
+            if '}' in linha:
+                dentro_da_interface = False
+                continue
+            
+            # 3. Captura o método com padrão Java: TipoRetorno nomeMetodo(Argumentos)
+            linha_limpa = linha.strip().replace(';', '')
+            if linha_limpa:
+                metodo_match = re.match(r'(?:\w+\s+)?(\w+)\s*\((.*?)\)', linha_limpa)
+                if metodo_match:
+                    nome_metodo = metodo_match.group(1)
+                    args_brutos = metodo_match.group(2)
+                    
+                    args_traduzidos = converter_tipos_java_para_python(args_brutos)
+                    
+                    resultado.append(f"    @abstractmethod")
+                    resultado.append(f"    def {nome_metodo}({args_traduzidos}):")
+                    resultado.append(f"        pass")
+        else:
+            resultado.append(linha)
+            
+    return '\n'.join(resultado)
+
+# --- INFRAESTRUTURA DE CODEC DO PYTHON ---
+
+class JavaInterfaceDecoder(codecs.BufferedIncrementalDecoder):
+    def _buffer_decode(self, input, errors, final):
+        if final:
+            dados_em_bytes = bytes(input)
+            texto_traduzido = traduzir_sintaxe_java(dados_em_bytes.decode('utf-8'))
+            return (texto_traduzido, len(input))
+        return ('', 0)
+
+def buscar_codec(nome_codec):
+    if nome_codec == 'py_interface':
+        return codecs.CodecInfo(
+            name='py_interface',
+            encode=codecs.utf_8_encode,
+            decode=lambda input, errors='strict': (traduzir_sintaxe_java(bytes(input).decode('utf-8')), len(input)),
+            incrementalencoder=codecs.utf_8_encode,
+            incrementaldecoder=JavaInterfaceDecoder,
+            streamreader=lambda stream, errors='strict': io.StringIO(traduzir_sintaxe_java(stream.read().decode('utf-8'))),
+            streamwriter=codecs.utf_8_encode
+        )
+    return None
+
+def registrar_syntax():
+    """Registra o tradutor de código dentro do núcleo de encodings do Python"""
+    codecs.register(buscar_codec)

pyinterfaces-0.2.0/pyproject.toml

@@ -0,0 +1,24 @@
+[project]
+name = "pyinterfaces"
+version = "0.2.0"
+description = "Interface in POO with Python"
+authors = [
+    {name = "Bruno Zolotareff",email = "brunozolotareff@gmail.com"}
+]
+readme = "README.md"
+keywords = ["interface", "java", "syntax", "brunozolotareff", "pyinterfaces"]
+packages = [{include = "pyinterfaces"}]
+license = "MIT"
+requires-python = ">=3.10"
+dependencies = [
+]
+
+
+[build-system]
+requires = ["poetry-core>=2.0.0,<3.0.0"]
+build-backend = "poetry.core.masonry.api"
+
+[dependency-groups]
+dev = [
+    "pytest (>=9.1.1,<10.0.0)"
+]

pyinterfaces-0.0.1/PKG-INFO

@@ -1,15 +0,0 @@
-Metadata-Version: 2.4
-Name: pyinterfaces
-Version: 0.0.1
-Summary: Interface in POO with Python
-Author: Bruno Zolotareff
-Author-email: brunozolotareff@gmail.com
-Requires-Python: >=3.8
-Classifier: Programming Language :: Python :: 3
-Classifier: Programming Language :: Python :: 3.8
-Classifier: Programming Language :: Python :: 3.9
-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

pyinterfaces-0.0.1/pyproject.toml

@@ -1,16 +0,0 @@
-[project]
-name = "pyinterfaces"
-version = "0.0.1"
-description = "Interface in POO with Python"
-authors = [
-    {name = "Bruno Zolotareff",email = "brunozolotareff@gmail.com"}
-]
-license = ""
-requires-python = ">=3.8"
-dependencies = [
-]
-
-
-[build-system]
-requires = ["poetry-core>=2.0.0,<3.0.0"]
-build-backend = "poetry.core.masonry.api"