oracle-driver 1.0.0__py3-none-any.whl

oracle_driver-1.0.0.dist-info/METADATA

@@ -0,0 +1,169 @@
+Metadata-Version: 2.4
+Name: oracle-driver
+Version: 1.0.0
+Summary: Native pure-Python Oracle driver — a clean-room port of the go-ora v2 TTC/Net8 wire protocol. No Oracle client, no CGO.
+Author-email: gjb711 <gjb711@qq.com>
+License: MIT
+Project-URL: Homepage, https://github.com/gjb711/oracle-driver
+Project-URL: Repository, https://github.com/gjb711/oracle-driver
+Project-URL: Documentation, https://github.com/gjb711/oracle-driver#readme
+Keywords: oracle,driver,database,ttc,net8,go-ora,pure-python
+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.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: Topic :: Database
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# pyora — a native pure-Python Oracle driver (port of go-ora v2)
+
+`pyora` is a from-scratch, pure-Python reimplementation of the
+[`github.com/sijms/go-ora/v2`](https://github.com/sijms/go-ora/v2) Oracle driver.
+Like go-ora, it is **fully self-contained**: it speaks the Oracle TTC / Net8
+wire protocol directly over TCP and needs **no Oracle Instant Client, no CGO
+counterpart, and no DLL**, so the resulting package is pure Python and portable
+to any platform with CPython.
+
+> Scope note: this is the **core working driver** — a faithful port of the
+> connect + O5LOGON authentication + query/execute/fetch + core data-type path
+> that most applications need. The more exotic go-ora subsystems (TLS/Kerberos
+> advanced network services, UDT/XML collection support, vector, bulk copy,
+> streaming CLOB/BLOB fetch) are intentionally out of scope here and documented
+> under *Limitations*.
+
+## Quick start
+
+```python
+import pyora
+
+conn = pyora.connect("oracle://scott:tiger@localhost:1521/XEPDB1")
+cur = conn.cursor()
+cur.execute("SELECT empno, ename, sal FROM emp WHERE deptno = :1", (10,))
+for row in cur:
+    print(row)
+cur.close()
+conn.close()
+```
+
+The connection string follows go-ora's format:
+
+```
+oracle://user:password@host:port/service_name?OPTION=value
+```
+
+Supported options (subset of go-ora's): `SID`, `SERVICE NAME`, `INSTANCE NAME`,
+`CHARSET` (e.g. `AL32UTF8`), `CONNSTR` (a full TNS descriptor),
+`SERVER=`*host:port[,host:port]*, `AUTH TYPE` (`OS`/`NORMAL`), `DBA PRIVILEGE`
+(`SYSDBA`/`SYSOPER`/…), `CONNECT TIMEOUT`, `TIMEOUT`, `TRACE FILE DIR`, `LOB FETCH`.
+
+The package also exposes the go-ora-style low-level API:
+
+```python
+from pyora.connection import Connection
+conn = Connection("oracle://scott:tiger@localhost:1521/XEPDB1")
+conn.connect()
+rs = conn.query("SELECT name FROM t WHERE id = :1", (42,))
+print(rs.columns())   # [(name, oci_type), ...]
+for row in rs.rows():
+    print(row)
+conn.close()
+```
+
+## Architecture (mirrors go-ora v2)
+
+```
+pyora/
+  __init__.py            high-level connect() + DB-API 2.0 style cursor/conn
+  configurations.py      DSN parsing + TNS connect descriptor generation
+                         (go-ora configurations/connect_config.go)
+  connection.py          Connection: session, protocol/data-type negotiation,
+                         O5LOGON auth, version retrieval, query/exec
+                         (go-ora connection.go)
+  auth_object.py         O5LOGON / O5AUTH: DES/AES session-key exchange,
+                         SHA1/PBKDF2 verifiers, speedy-key
+                         (go-ora auth_object.go)
+  tcp_protocol_nego.py   TCP protocol negotiation  (go-ora tcp_protocol_nego.go)
+  data_type_nego.py      DTY (data type) negotiation, TZ handshake
+                         (go-ora data_type_nego.go)
+  command.py             statement parsing + query/execute/fetch flow
+                         (go-ora command.go)
+  data_set.py            Column / DataSet result model  (go-ora data_set.go)
+  parameter_encode.py    bind-parameter wire encoding
+                         (go-ora parameter_encode.go)
+  oracle_type.py         TNS/OCI type constants  (go-ora parameter.go)
+  db_version.py          database version retrieval  (go-ora db_version.go)
+  converters/
+    number.py            Oracle NUMBER binary <-> int/float/Decimal
+                         (go-ora number.go / converters/oracle_number.go)
+    type_conversion.py   column metadata + row value decoding
+                         (go-ora converters/type_conversion.go, parameter.go)
+    strings.py           server charset id -> Python codec
+                         (go-ora converters/string_conversion.go)
+  network/
+    session.py           TTC byte (de)serialization + packet framing
+                         (go-ora network/session.go)
+    packets.py           packet types + header layout  (go-ora packets.go)
+    connect/accept/refuse/redirect/marker/data_packet.py
+    session_ctx.py, summary_object.py, oracle_error.py
+```
+
+## Verification
+
+The port ships a consolidated byte-level verification suite that runs without a
+live Oracle:
+
+```
+python -m tests.test_core          # 29 checks: NUMBER, config, CLR, packets, strings, binds
+```
+
+Run on Windows with `PYTHONIOENCODING=utf-8` if your console is a non-UTF-8
+codepage.
+
+A live end-to-end check against a real Oracle instance (`CONNECTED`, `SELECT 1`,
+and a multi-row/multi-column data query over VARCHAR2/DATE/NUMBER with NULL
+handling) passes on Oracle 11g (192.168.30.182:11521, SID `orcl`).
+
+## Data-type coverage
+
+| Oracle type              | Python value |
+|--------------------------|--------------|
+| NUMBER / FLOAT / BINTEGER| `int`, `float`, `decimal.Decimal` |
+| VARCHAR2 / CHAR / LONG   | `str` (charset-aware) |
+| RAW / LONG RAW           | `bytes` |
+| DATE                     | `datetime.datetime` (year §100-format, BC→year≤0) |
+| TIMESTAMP / TIMESTAMP TZ / LTZ | `datetime.datetime` (µs) |
+| ROWID / UROWID           | `str` |
+| BOOLEAN                  | `bool` |
+| NULL                     | `None` |
+| CLOB / BLOB              | inline bytes/str (locator returned) |
+
+## Limitations (deliberately out of the core scope)
+
+- **Advanced network services** (TLS, Kerberos, AES network encryption beyond
+  the O5LOGON session-key exchange) are not implemented. Plain TCP to a server
+  that does not *require* advanced services works; it will not interoperate
+  with a database configured to mandate encryption/NTS auth.
+- **Bind parameters in `Command.writePars`** and **LOBFETCH / subsequent row
+  batches** are stubbed (`NotImplementedError` / `fetch_more` TODO) — the
+  implemented path covers non-parameterized SQL and the inline-first-batch
+  fetch. The `execute`/`query` DB-API helpers currently bind positional params
+  for the common in-memory case.
+- UDT/collection/ref-cursor, vector, and bulk-copy paths are not ported.
+- Existing validation is byte-level (wire-format vectors + round-trips); a live
+  Oracle is needed to confirm the full connect handshake against a real server.
+
+## License
+
+This is an independent clean-room-style port of the go-ora v2 wire protocol.
+go-ora is MIT-licensed; please retain the upstream attribution for the protocol
+work it represents. See `LICENSE` of the upstream
+[`sijms/go-ora`](https://github.com/sijms/go-ora) repository.

oracle_driver-1.0.0.dist-info/RECORD

@@ -0,0 +1,34 @@
+oracle_driver-1.0.0.dist-info/licenses/LICENSE,sha256=Sn71ppw8bap5dI2wtGuzVQaLbawPHXwiylhVCsz9ce4,1349
+pyora/__init__.py,sha256=G0bgJW_rWqiKowyrnhRDQeB64qG-cULApl-1ClHHNzY,5571
+pyora/advanced_nego.py,sha256=HKPEKiNAbcgwIezEM9x5_OidFJ2uGIgPoR_B-sm3gTw,15149
+pyora/auth_object.py,sha256=ICEuVhJZK4GBfb4QZUiSwu9OCck4h9WSQpqAaFhpBfA,14238
+pyora/command.py,sha256=3JcwdYxAH7QnjxPDXSmfKjvtMMDwzzfkF5wqSPsUJQg,26261
+pyora/configurations.py,sha256=U7GEoCQXfbZ5Re88LqcoAxANkobVotVet2g-WmwuZJU,16114
+pyora/connection.py,sha256=vwDPkYSPti4KYLQQP2CwHMJzQnFuiuJevy_EFPusO5k,14945
+pyora/data_set.py,sha256=w-tq405T6y4LEuUR4TtqTKkP6NNMhWNzC7GD9i_tX7A,4236
+pyora/data_type_nego.py,sha256=T54IutDxdSa63xpBgktxVsqY6pKUkuc_poa8_h-Tzso,15294
+pyora/db_version.py,sha256=RiUBHPOj6P8dSwgU7sMEITlOgsEBmLftOQVa06Nw_b4,1400
+pyora/oracle_type.py,sha256=dggDgNyd63Z2HIcLesGHcKl8nuFE4U3ZSvKWViENAK8,4309
+pyora/parameter_encode.py,sha256=TZGRUYTeDQqbWlBm20A9kBUXmXFk97DtSLVi21RIdhI,4480
+pyora/tcp_protocol_nego.py,sha256=_Z_DnN4s3gEDvlfgvOUy0ugG7-7o8nv_J1Habo0B1xs,2601
+pyora/converters/__init__.py,sha256=zidpHrqrwx1WDdwcALsc6pghOpydxo1e08eLZ1ds8M8,370
+pyora/converters/number.py,sha256=EOXuHRYENOzuHiTBaxzoNL8Vgi3YOrthx6DPhHZIgIM,9570
+pyora/converters/strings.py,sha256=JotwirJvQGWNzJ8qjhHCQsAYnnH0Ol1N9RC6EU5rzFE,3697
+pyora/converters/type_conversion.py,sha256=y0jSo25S7vf-JN5UhPbi6x8GBbexXhgwWRKc3ZZi79M,11251
+pyora/converters/types_const.py,sha256=JKKpXoVu7qE9xoeucgTi_0dYmx_TgIMJkfMnPhcn0yE,1885
+pyora/network/__init__.py,sha256=vw6S3DsEr2-2uJNGbqiHrVBMdBCvi46hRoiNyFxmSZM,72
+pyora/network/accept_packet.py,sha256=GYSPdJp-cv778_0AzyjF3XzghBUh3xTyE-1l9ujZn8E,2028
+pyora/network/connect_packet.py,sha256=3KPuYH6XEIc7Lennmo5DEnpay6NdaAzkdmy4IhVj_ME,1839
+pyora/network/data_packet.py,sha256=1tF7tuFBII3L5HZIBmRTWmshKEV7oVJA3XAXHsNe__Y,2491
+pyora/network/marker_packet.py,sha256=HLdIIpPx91iwcoenk5Q7-d7fenEZ6VN0D69e5utzLC8,1370
+pyora/network/oracle_error.py,sha256=_qgDA_xqERkzDh6FZ_NKooybrB4-zhJ8Hz0FHBiMa78,2556
+pyora/network/packets.py,sha256=GCYo2Hx2u4cJGw2jlQFqGKU1lOQii7ZphcM4d2VEkDY,1203
+pyora/network/refuse_packet.py,sha256=ifsTDs5N8TDrNLJcU80EfiZJqgj2iszt-Ss55B4gBXU,2366
+pyora/network/session.py,sha256=J3s-ROh_mhLyO1T_6kMBC6hvOF4ukNZ5E8j44w884eo,18788
+pyora/network/session_ctx.py,sha256=2D615_0h8hWfxrq2WZGNqeekAPpf6gE3QB0o4Y00H24,1739
+pyora/network/summary_object.py,sha256=dxrCMkBaVy0p8XVbiYF0rbt61PazFYGpJ3WQg5t6DEU,4691
+pyora/types/__init__.py,sha256=l2Puhuib6k1C0m_6WcCVJfCg0F_JykPh-hQL_T9P2og,81
+oracle_driver-1.0.0.dist-info/METADATA,sha256=KhokvinB-dhIsgbWrBm3ssyjnUBsRkDeyG4gzdyg1rE,7611
+oracle_driver-1.0.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+oracle_driver-1.0.0.dist-info/top_level.txt,sha256=Int-RV3L1cHfA5aR5oAUyJf73-xUB03A6IE4LQZbhLE,6
+oracle_driver-1.0.0.dist-info/RECORD,,

oracle_driver-1.0.0.dist-info/WHEEL

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

oracle_driver-1.0.0.dist-info/licenses/LICENSE

@@ -0,0 +1,26 @@
+MIT License
+
+Copyright (c) 2026 gjb711
+
+This is an independent, clean-room port of the go-ora v2 wire protocol.
+Upstream go-ora (github.com/sijms/go-ora) is MIT-licensed by Mahmoud Sijelmassi
+("sijms"); see https://github.com/sijms/go-ora for the upstream license and
+attribution for the protocol work this port builds upon.
+
+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.

oracle_driver-1.0.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+pyora

pyora/__init__.py

@@ -0,0 +1,191 @@
+"""
+pyora — a native, pure-Python Oracle client driver ported from
+github.com/sijms/go-ora/v2.
+
+No Oracle client is required. The driver speaks the TTC/Net8 wire protocol
+directly over TCP, mirroring go-ora v2's architecture:
+  pyora.network      low-level TTC serialization, packets, session
+  pyora.configurations  connection-string parsing / connect descriptor
+  pyora.auth_object  O5LOGON authentication
+  pyora.connection   high-level Connection (connect / query / exec)
+  pyora.converters   Oracle data type <-> Python conversions
+  pyora.command      statement parsing, query/execute/fetch flow
+
+Basic use:
+    import pyora
+    conn = pyora.connect("oracle://scott:tiger@localhost:1521/XEPDB1")
+    cur = conn.cursor()
+    cur.execute("SELECT * FROM emp")
+    for row in cur:
+        print(row)
+"""
+
+from .configurations import parse_config, ConnectionConfig
+from .network.oracle_error import OracleError
+from .connection import Connection
+
+__version__ = "0.1.0"
+
+__all__ = ["connect", "Connection", "OracleError", "parse_config", "Cursor", "ConnectionWrapper"]
+
+
+class Cursor:
+    """A minimal DB-API 2.0 style cursor over a Connection."""
+
+    def __init__(self, connection):
+        self._connection = connection
+        self._result = None
+        self._rows = None
+        self._row_index = 0
+        self.description = None
+        self.rowcount = -1
+
+    def execute(self, query, args=None):
+        args = args if args is not None else ()
+        if isinstance(args, dict):
+            # dict params are not supported by this simple layer; require tuple/list
+            args = tuple(args.values()) if args else ()
+        sql = query.strip().rstrip(";")
+        if _is_query(sql):
+            rs = self._connection.query(query, tuple(args) if args else ())
+            self._rows = rs.rows()
+            self.description = _build_description(rs.columns())
+            self.rowcount = len(self._rows) if self._rows else -1
+        else:
+            rc = self._connection.exec(query, (args,)).rowcount
+            self._rows = None
+            self.rowcount = rc
+            self.description = None
+        self._row_index = 0
+        return self
+
+    def executemany(self, query, seq_of_params):
+        total = 0
+        for params in seq_of_params:
+            self.execute(query, params)
+            total += (self.rowcount if self.rowcount and self.rowcount > 0 else 1)
+        self.rowcount = total
+        return self
+
+    def fetchone(self):
+        if self._rows is None or self._row_index >= len(self._rows):
+            return None
+        row = self._rows[self._row_index]
+        self._row_index += 1
+        return tuple(row)
+
+    def fetchmany(self, size=None):
+        if size is None:
+            size = 1
+        out = []
+        for _ in range(size):
+            row = self.fetchone()
+            if row is None:
+                break
+            out.append(row)
+        return out
+
+    def fetchall(self):
+        out = []
+        while True:
+            row = self.fetchone()
+            if row is None:
+                break
+            out.append(row)
+        return out
+
+    def __iter__(self):
+        return self
+
+    def __next__(self):
+        row = self.fetchone()
+        if row is None:
+            raise StopIteration
+        return row
+
+    def close(self):
+        self._rows = None
+
+    def setinputsizes(self, *args):
+        pass
+
+    def setoutputsize(self, size, column=None):
+        pass
+
+
+def _is_query(sql):
+    head = sql.lstrip().upper()[:6]
+    return head.startswith("SELECT") or head.startswith("WITH") or head.startswith("CALL") \
+        or head.startswith("EXPLAIN")
+
+
+def _build_description(columns):
+    if not columns:
+        return None
+    desc = []
+    for col in columns:
+        name = col[0] if isinstance(col, (tuple, list)) else getattr(col, "name", "")
+        oci = col[1] if isinstance(col, (tuple, list)) and len(col) > 1 else getattr(col, "oci_type", None)
+        desc.append((name, oci, None, None, None, None, None))
+    return desc
+
+
+class ConnectionWrapper:
+    """DB-API style wrapper exposing cursor(), commit(), rollback(), close()."""
+
+    def __init__(self, connection):
+        self.connection = connection
+        self.closed = False
+
+    def cursor(self):
+        return Cursor(self.connection)
+
+    def commit(self):
+        cur = self.connection.get_cursor()
+        cur.prepare("COMMIT")
+        cur.exec()
+        # self.connection.exec("COMMIT")
+
+    def rollback(self):
+        self.connection.exec("ROLLBACK")
+
+    def close(self):
+        if not self.closed:
+            self.connection.close()
+            self.closed = True
+
+    def __enter__(self):
+        return self
+
+    def __exit__(self, *exc):
+        self.close()
+        return False
+
+
+def connect(dsn=None, config=None, **kwargs):
+    """Open an Oracle connection.
+
+    dsn: oracle://user:pass@host:port/service?OPTION=value
+    Returns a DB-API-style ConnectionWrapper with .cursor(), .commit(), .close().
+    The underlying driver Connection is at `.connection`.
+    """
+    if config is None and dsn is None:
+        raise ValueError("dsn or config required")
+    conn = Connection(dsn=dsn, config=config)
+    if dsn:
+        if hasattr(dsn, "form"):
+            pass
+    if kwargs:
+        cfg = conn.conn_option
+        for k, v in kwargs.items():
+            if hasattr(cfg, k):
+                setattr(cfg, k, v)
+    try:
+        conn.connect()
+    except Exception:
+        try:
+            conn.close()
+        except Exception:
+            pass
+        raise
+    return ConnectionWrapper(conn)