pyxsql 1.0.0__cp313-cp313-win32.whl

pyxsql-1.0.0.dist-info/METADATA

@@ -0,0 +1,580 @@
+Metadata-Version: 2.4
+Name: pyxsql
+Version: 1.0.0
+Summary: SQL-style querying for static HTML with a deterministic node model.
+Author: BORANN CHANRATHNAK
+License:                                  Apache License
+                                   Version 2.0, January 2004
+                                http://www.apache.org/licenses/
+        
+           TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+        
+           1. Definitions.
+        
+              "License" shall mean the terms and conditions for use, reproduction,
+              and distribution as defined by Sections 1 through 9 of this document.
+        
+              "Licensor" shall mean the copyright owner or entity authorized by
+              the copyright owner that is granting the License.
+        
+              "Legal Entity" shall mean the union of the acting entity and all
+              other entities that control, are controlled by, or are under common
+              control with that entity. For the purposes of this definition,
+              "control" means (i) the power, direct or indirect, to cause the
+              direction or management of such entity, whether by contract or
+              otherwise, or (ii) ownership of fifty percent (50%) or more of the
+              outstanding shares, or (iii) beneficial ownership of such entity.
+        
+              "You" (or "Your") shall mean an individual or Legal Entity
+              exercising permissions granted by this License.
+        
+              "Source" form shall mean the preferred form for making modifications,
+              including but not limited to software source code, documentation
+              source, and configuration files.
+        
+              "Object" form shall mean any form resulting from mechanical
+              transformation or translation of a Source form, including but
+              not limited to compiled object code, generated documentation,
+              and conversions to other media types.
+        
+              "Work" shall mean the work of authorship, whether in Source or
+              Object form, made available under the License, as indicated by a
+              copyright notice that is included in or attached to the work
+              (an example is provided in the Appendix below).
+        
+              "Derivative Works" shall mean any work, whether in Source or Object
+              form, that is based on (or derived from) the Work and for which the
+              editorial revisions, annotations, elaborations, or other modifications
+              represent, as a whole, an original work of authorship. For the purposes
+              of this License, Derivative Works shall not include works that remain
+              separable from, or merely link (or bind by name) to the interfaces of,
+              the Work and Derivative Works thereof.
+        
+              "Contribution" shall mean any work of authorship, including
+              the original version of the Work and any modifications or additions
+              to that Work or Derivative Works thereof, that is intentionally
+              submitted to Licensor for inclusion in the Work by the copyright owner
+              or by an individual or Legal Entity authorized to submit on behalf of
+              the copyright owner. For the purposes of this definition, "submitted"
+              means any form of electronic, verbal, or written communication sent
+              to the Licensor or its representatives, including but not limited to
+              communication on electronic mailing lists, source code control systems,
+              and issue tracking systems that are managed by, or on behalf of, the
+              Licensor for the purpose of discussing and improving the Work, but
+              excluding communication that is conspicuously marked or otherwise
+              designated in writing by the copyright owner as "Not a Contribution."
+        
+              "Contributor" shall mean Licensor and any individual or Legal Entity
+              on behalf of whom a Contribution has been received by Licensor and
+              subsequently incorporated within the Work.
+        
+           2. Grant of Copyright License. Subject to the terms and conditions of
+              this License, each Contributor hereby grants to You a perpetual,
+              worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+              copyright license to reproduce, prepare Derivative Works of,
+              publicly display, publicly perform, sublicense, and distribute the
+              Work and such Derivative Works in Source or Object form.
+        
+           3. Grant of Patent License. Subject to the terms and conditions of
+              this License, each Contributor hereby grants to You a perpetual,
+              worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+              (except as stated in this section) patent license to make, have made,
+              use, offer to sell, sell, import, and otherwise transfer the Work,
+              where such license applies only to those patent claims licensable
+              by such Contributor that are necessarily infringed by their
+              Contribution(s) alone or by combination of their Contribution(s)
+              with the Work to which such Contribution(s) was submitted. If You
+              institute patent litigation against any entity (including a
+              cross-claim or counterclaim in a lawsuit) alleging that the Work
+              or a Contribution incorporated within the Work constitutes direct
+              or contributory patent infringement, then any patent licenses
+              granted to You under this License for that Work shall terminate
+              as of the date such litigation is filed.
+        
+           4. Redistribution. You may reproduce and distribute copies of the
+              Work or Derivative Works thereof in any medium, with or without
+              modifications, and in Source or Object form, provided that You
+              meet the following conditions:
+        
+              (a) You must give any other recipients of the Work or
+                  Derivative Works a copy of this License; and
+        
+              (b) You must cause any modified files to carry prominent notices
+                  stating that You changed the files; and
+        
+              (c) You must retain, in the Source form of any Derivative Works
+                  that You distribute, all copyright, patent, trademark, and
+                  attribution notices from the Source form of the Work,
+                  excluding those notices that do not pertain to any part of
+                  the Derivative Works; and
+        
+              (d) If the Work includes a "NOTICE" text file as part of its
+                  distribution, then any Derivative Works that You distribute must
+                  include a readable copy of the attribution notices contained
+                  within such NOTICE file, excluding those notices that do not
+                  pertain to any part of the Derivative Works, in at least one
+                  of the following places: within a NOTICE text file distributed
+                  as part of the Derivative Works; within the Source form or
+                  documentation, if provided along with the Derivative Works; or,
+                  within a display generated by the Derivative Works, if and
+                  wherever such third-party notices normally appear. The contents
+                  of the NOTICE file are for informational purposes only and
+                  do not modify the License. You may add Your own attribution
+                  notices within Derivative Works that You distribute, alongside
+                  or as an addendum to the NOTICE text from the Work, provided
+                  that such additional attribution notices cannot be construed
+                  as modifying the License.
+        
+              You may add Your own copyright statement to Your modifications and
+              may provide additional or different license terms and conditions
+              for use, reproduction, or distribution of Your modifications, or
+              for any such Derivative Works as a whole, provided Your use,
+              reproduction, and distribution of the Work otherwise complies with
+              the conditions stated in this License.
+        
+           5. Submission of Contributions. Unless You explicitly state otherwise,
+           any Contribution intentionally submitted for inclusion in the Work
+           by You to the Licensor shall be under the terms and conditions of
+           this License, without any additional terms or conditions.
+           Notwithstanding the above, nothing herein shall supersede or modify
+           the terms of any separate license agreement you may have executed
+           with Licensor regarding such Contributions.
+        
+           6. Trademarks. This License does not grant permission to use the trade
+           names, trademarks, service marks, or product names of the Licensor,
+           except as required for reasonable and customary use in describing the
+           origin of the Work and reproducing the content of the NOTICE file.
+        
+           7. Disclaimer of Warranty. Unless required by applicable law or
+           agreed to in writing, Licensor provides the Work (and each
+           Contributor provides its Contributions) on an "AS IS" BASIS,
+           WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+           implied, including, without limitation, any warranties or conditions
+           of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+           PARTICULAR PURPOSE. You are solely responsible for determining the
+           appropriateness of using or redistributing the Work and assume any
+           risks associated with Your exercise of permissions under this License.
+        
+           8. Limitation of Liability. In no event and under no legal theory,
+           whether in tort (including negligence), contract, or otherwise,
+           unless required by applicable law (such as deliberate and grossly
+           negligent acts) or agreed to in writing, shall any Contributor be
+           liable to You for damages, including any direct, indirect, special,
+           incidental, or consequential damages of any character arising as a
+           result of this License or out of the use or inability to use the
+           Work (including but not limited to damages for loss of goodwill,
+           work stoppage, computer failure or malfunction, or any and all
+           other commercial damages or losses), even if such Contributor
+           has been advised of the possibility of such damages.
+        
+           9. Accepting Warranty or Additional Liability. While redistributing
+           the Work or Derivative Works thereof, You may choose to offer,
+           and charge a fee for, acceptance of support, warranty, indemnity,
+           or other liability obligations and/or rights consistent with this
+           License. However, in accepting such obligations, You may act only
+           on Your own behalf and on Your sole responsibility, not on behalf
+           of any other Contributor, and only if You agree to indemnify,
+           defend, and hold each Contributor harmless for any liability
+           incurred by, or claims asserted against, such Contributor by reason
+           of your accepting any such warranty or additional liability.
+        
+           END OF TERMS AND CONDITIONS
+        
+           Copyright 2025 BORANN CHANRATHNAK
+        
+           Licensed under the Apache License, Version 2.0 (the "License");
+           you may not use this file except in compliance with the License.
+           You may obtain a copy of the License at
+        
+               http://www.apache.org/licenses/LICENSE-2.0
+        
+           Unless required by applicable law or agreed to in writing, software
+           distributed under the License is distributed on an "AS IS" BASIS,
+           WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+           See the License for the specific language governing permissions and
+           limitations under the License.
+        
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: C++
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: test
+Requires-Dist: pytest>=7.4.0; extra == "test"
+Dynamic: license-file
+
+# XSQL Documentation (v1.0.0)
+
+XSQL is a SQL-style query language for static HTML. It treats each HTML element
+as a row in a node table and lets you filter by tag and attributes. The project
+has now flourished to v1.0.0 as an offline-first C++20 tool.
+
+## Quick Start
+
+Build:
+```
+./build.sh
+```
+
+Run on a file:
+```
+./build/xsql --query "SELECT a FROM doc WHERE attributes.id = 'login'" --input ./data/index.html
+```
+
+Interactive mode:
+```
+./build/xsql --interactive --input ./data/index.html
+```
+
+## Python API (xsql package)
+
+```python
+import xsql
+
+doc = xsql.load("data/index.html")
+print(xsql.summarize(doc))
+rows = xsql.execute("SELECT a FROM document WHERE attributes.href IS NOT NULL")
+
+doc = xsql.load("https://example.com", allow_network=True)
+rows = xsql.execute("SELECT title FROM document")
+```
+
+Install:
+```
+pip install pyxsql
+```
+
+Security Notes:
+- Network access is disabled by default; enable with `allow_network=True`.
+- Private/localhost targets are blocked unless `allow_private_network=True`.
+- File reads are confined to `base_dir` when provided.
+- Downloads are capped by `max_bytes`, and query output by `max_results`.
+
+## Build on Linux/macOS/Windows
+
+Linux (Ubuntu/Debian):
+```
+sudo apt-get update
+sudo apt-get install -y build-essential cmake ninja-build pkg-config bison flex
+./build.sh
+```
+
+macOS (Homebrew):
+```
+brew install cmake ninja pkg-config bison flex
+./build.sh
+```
+
+Windows (PowerShell, MSVC):
+```
+cmake -S . -B build -DCMAKE_TOOLCHAIN_FILE=C:\vcpkg\scripts\buildsystems\vcpkg.cmake -DVCPKG_TARGET_TRIPLET=x64-windows
+cmake --build build --config Release
+```
+
+Optional dependencies via vcpkg:
+```
+vcpkg install nlohmann-json libxml2 curl arrow[parquet]
+```
+
+If you do not want Parquet, configure with `-DXSQL_WITH_ARROW=OFF`.
+
+## Python Build & Tests
+
+Create a virtual environment and install the editable package:
+```
+python3 -m venv xsql_venv
+source ./xsql_venv/bin/activate
+pip install -U pip
+pip install -e .[test]
+```
+
+Run Python tests:
+```
+pytest -v python/tests
+```
+
+Shorthand:
+```
+./test_python.sh
+```
+
+## CLI Usage
+
+```
+./build/xsql --query "<query>" --input <path>
+./build/xsql --query-file <file> --input <path>
+./build/xsql --interactive [--input <path>]
+./build/xsql --mode duckbox|json|plain
+./build/xsql --highlight on|off
+./build/xsql --color=disabled
+```
+
+Notes:
+- `--input` is required unless reading HTML from stdin.
+- Colors are auto-disabled when stdout is not a TTY.
+- Default output mode is `duckbox` (table-style).
+- `--highlight` only affects duckbox headers (auto-disabled when not a TTY).
+- `TO CSV()` / `TO PARQUET()` write files instead of printing results.
+
+## Interactive Mode (REPL)
+
+Commands:
+- `.help`: show help
+- `.load <path|url>` / `:load <path|url>`: load input (path or URL)
+- `.mode duckbox|json|plain`: set output mode
+- `.display_mode more|less`: control JSON truncation
+- `.max_rows <n|inf>`: set duckbox max rows (`inf` = unlimited)
+- `.summarize [doc|path|url]`: list all tags and counts for the active input or target
+- `.quit` / `.q` / `:quit` / `:exit`: exit the REPL
+
+Keys:
+- Up/Down: history (max 5 entries)
+- Left/Right: move cursor
+- Ctrl+L: clear screen
+
+## Data Model
+
+Each HTML element becomes a row with fields:
+- `node_id` (int64)
+- `tag` (string)
+- `attributes` (map<string,string>)
+- `parent_id` (int64 or null)
+- `source_uri` (string)
+
+## Query Language
+
+### Basic Form
+```
+SELECT <tag_list> FROM <source> [WHERE <expr>] [LIMIT <n>]
+  [TO LIST() | TO TABLE() | TO CSV('file.csv') | TO PARQUET('file.parquet')]
+```
+
+### Source
+```
+FROM document
+FROM 'path.html'
+FROM 'https://example.com'   (URL fetching requires libcurl)
+FROM doc                     (alias for document)
+FROM document AS doc
+```
+
+### Tags
+```
+SELECT div
+SELECT div,span
+SELECT *
+```
+
+Exclude columns:
+```
+SELECT * EXCLUDE source_uri FROM doc
+SELECT * EXCLUDE (source_uri, tag) FROM doc
+```
+
+### WHERE Expressions
+Supported operators:
+- `=`
+- `IN`
+- `<>` / `!=`
+- `IS NULL` / `IS NOT NULL`
+- `~` (regex, ECMAScript)
+- `AND`, `OR`
+
+Attribute references:
+```
+attributes.id = 'main'
+parent.attributes.class = 'menu'
+child.attributes.href <> ''
+ancestor.attributes.id = 'root'
+descendant.attributes.class IN ('nav','top')
+```
+
+Field references:
+```
+text <> ''
+tag = 'div'
+parent.tag = 'section'
+child.tag = 'a'
+ancestor.text ~ 'error|warning'
+```
+
+Shorthand attribute filters:
+```
+title = "Menu"
+doc.title = "Menu"
+```
+
+### Aliases
+Alias the source and qualify attribute filters:
+```
+SELECT a FROM document AS d WHERE d.attributes.id = 'login'
+```
+
+### Projections
+Project a field from a tag:
+```
+SELECT a.parent_id FROM doc
+SELECT link.href FROM doc
+SELECT a.attributes FROM doc
+SELECT div(node_id, tag, parent_id) FROM doc
+```
+
+Supported base fields:
+- `node_id`, `tag`, `parent_id`, `source_uri`, `attributes`
+
+Attribute value projection:
+- `SELECT link.href FROM doc` returns the `href` value
+
+Function projection:
+- `SELECT inner_html(div) FROM doc` returns the raw inner HTML for each `div`
+- `SELECT inner_html(div, 1) FROM doc` keeps only tags up to depth 1 (drops deeper tags)
+- `SELECT trim(inner_html(div)) FROM doc` trims leading/trailing whitespace
+- `SELECT TEXT(div) FROM doc WHERE tag = 'div'` returns descendant text for each `div`
+
+Notes:
+- `TEXT()` and `INNER_HTML()` require a `WHERE` clause with a non-tag filter (e.g., attributes or parent).
+- `attributes IS NULL` matches elements with no attributes.
+
+### TO LIST()
+Output a JSON list for a single projected column:
+```
+SELECT link.href FROM doc WHERE attributes.rel = "preload" TO LIST()
+```
+
+### TO TABLE()
+Extract an HTML `<table>` into rows (array of arrays):
+```
+SELECT table FROM doc TO TABLE()
+```
+
+If multiple tables match, the output is a list of objects:
+```
+[{ "node_id": 123, "rows": [[...], ...] }, ...]
+```
+
+Note: `TO LIST()` always returns JSON output. `TO TABLE()` uses duckbox by default and JSON in `--mode json|plain`.
+
+### TO CSV()
+Write any rectangular result to a CSV file:
+```
+SELECT a.href, a.text FROM doc WHERE attributes.href IS NOT NULL TO CSV('links.csv')
+```
+
+### TO PARQUET()
+Write any rectangular result to a Parquet file (requires Apache Arrow feature):
+```
+SELECT * FROM doc TO PARQUET('nodes.parquet')
+```
+
+Note: `TO CSV()` and `TO PARQUET()` write files and do not print the result set.
+If you `SELECT table ... TO CSV(...)`, XSQL exports the HTML table rows directly.
+
+### LIMIT
+```
+SELECT a FROM doc LIMIT 5
+```
+
+### COUNT()
+Minimal aggregate:
+```
+SELECT COUNT(a) FROM doc
+SELECT COUNT(*) FROM doc
+SELECT COUNT(link) FROM doc WHERE attributes.rel = "preload"
+```
+
+### Regex
+Use `~` with ECMAScript regex:
+```
+SELECT a FROM doc WHERE attributes.href ~ '.*\\.pdf$'
+```
+
+## Examples
+
+Select by id:
+```
+SELECT ul FROM doc WHERE attributes.id = 'countries';
+```
+
+Parent attribute filter:
+```
+SELECT table FROM doc WHERE parent.attributes.id = 'table-01';
+```
+
+Descendant attribute filter:
+```
+SELECT div FROM doc WHERE descendant.attributes.class = 'card';
+```
+
+Extract href list:
+```
+SELECT link.href FROM doc WHERE attributes.rel = "preload" TO LIST();
+```
+
+Export to CSV:
+```
+SELECT a.href, a.text FROM doc WHERE attributes.href IS NOT NULL TO CSV('links.csv');
+```
+
+Export to Parquet:
+```
+SELECT * FROM doc TO PARQUET('nodes.parquet');
+```
+
+Order results:
+```
+SELECT div FROM doc ORDER BY node_id DESC;
+```
+```
+SELECT * FROM doc ORDER BY tag, parent_id LIMIT 10;
+```
+
+Summarize tags:
+```
+SELECT summarize(*) FROM doc;
+```
+
+Top tags:
+```
+SELECT summarize(*) FROM doc ORDER BY count DESC LIMIT 5;
+```
+
+Filter by parent node id:
+```
+SELECT span FROM doc WHERE parent_id = 1;
+```
+
+Filter by node id:
+```
+SELECT span FROM doc WHERE node_id = 1;
+```
+
+Match elements with no attributes:
+```
+SELECT div FROM doc WHERE attributes IS NULL;
+```
+
+## Known Limitations (v0.1)
+
+- No XPath or positional predicates.
+- `ORDER BY` is limited to `node_id`, `tag`, `text`, or `parent_id`.
+- No `GROUP BY` or joins.
+- No XML mode (HTML only).
+- URL fetching requires libcurl.
+- Default output is duckbox tables; JSON output is available via `--mode json`.
+- `TO PARQUET()` requires Apache Arrow support at build time.
+
+## Build Dependencies
+
+Optional:
+- `nlohmann/json` for pretty JSON output (vcpkg recommended).
+- `libxml2` for robust HTML parsing (fallback to naive parser if missing).
+- `libcurl` for URL fetching.
+- `apache-arrow` (Arrow/Parquet) for `TO PARQUET()` export.
+
+## Troubleshooting
+
+- If you see `No input loaded` in REPL, run `:load <path|url>`.
+- If a query fails with `Expected FROM`, include a `FROM` clause.
+- If output is compact JSON, ensure `nlohmann/json` is linked via vcpkg.

pyxsql-1.0.0.dist-info/RECORD

@@ -0,0 +1,12 @@
+pyxsql-1.0.0.dist-info/licenses/LICENSE,sha256=px6L0kBMsqHVBArERkmFyUELFcRWoeNo543SSrrZbpo,10845
+xsql/__init__.py,sha256=Yr_1yuWpsnqoyUAJT7lb8Ggz3_LF6GmDsm_8pkQblCM,4133
+xsql/_core.cp313-win32.pyd,sha256=Ao28DX3rUekezu8zez2eFKB9w0_YLpDtThHBhLqMvg4,280064
+xsql/_core.cpp,sha256=lXU-vAEKcnWfyTwiM5_evlOSbNkvWWVjF1_Tckao0Oc,2887
+xsql/_loader.py,sha256=i7TfyVVAYWXpjGrXKbbUro6neR5mujS58GGWQU8PvuA,5415
+xsql/_security.py,sha256=ztH9c85IKRmSCz6Tq-4hKo8ZmGBKiW5RfPcUzaMwoNA,2562
+xsql/_summary.py,sha256=m1NsL3Y4QS0fmkuLCI2o722MmwdazTC4PXwPPUFpDsg,1202
+xsql/_types.py,sha256=j7mXDCUfyE5sirZFP0jzpBMpB76y9plowc6LMdKfA7M,868
+pyxsql-1.0.0.dist-info/METADATA,sha256=EcK7YtxZ-yl_ym40UhmScjMd26TDNHOYvh8xp_p93Zc,21846
+pyxsql-1.0.0.dist-info/WHEEL,sha256=0ABLuJ37exXk5N_efmYNs2NU9NK1K2Qlod_6bYkofEA,97
+pyxsql-1.0.0.dist-info/top_level.txt,sha256=1W3QSZQ6L-T6Jmonfe0IRGC7DRYRwIOaX9wKcV53RHQ,5
+pyxsql-1.0.0.dist-info/RECORD,,

pyxsql-1.0.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (80.9.0)
+Root-Is-Purelib: false
+Tag: cp313-cp313-win32
+

pyxsql-1.0.0.dist-info/licenses/LICENSE

@@ -0,0 +1,190 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+   any Contribution intentionally submitted for inclusion in the Work
+   by You to the Licensor shall be under the terms and conditions of
+   this License, without any additional terms or conditions.
+   Notwithstanding the above, nothing herein shall supersede or modify
+   the terms of any separate license agreement you may have executed
+   with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+   names, trademarks, service marks, or product names of the Licensor,
+   except as required for reasonable and customary use in describing the
+   origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+   agreed to in writing, Licensor provides the Work (and each
+   Contributor provides its Contributions) on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+   implied, including, without limitation, any warranties or conditions
+   of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+   PARTICULAR PURPOSE. You are solely responsible for determining the
+   appropriateness of using or redistributing the Work and assume any
+   risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+   whether in tort (including negligence), contract, or otherwise,
+   unless required by applicable law (such as deliberate and grossly
+   negligent acts) or agreed to in writing, shall any Contributor be
+   liable to You for damages, including any direct, indirect, special,
+   incidental, or consequential damages of any character arising as a
+   result of this License or out of the use or inability to use the
+   Work (including but not limited to damages for loss of goodwill,
+   work stoppage, computer failure or malfunction, or any and all
+   other commercial damages or losses), even if such Contributor
+   has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+   the Work or Derivative Works thereof, You may choose to offer,
+   and charge a fee for, acceptance of support, warranty, indemnity,
+   or other liability obligations and/or rights consistent with this
+   License. However, in accepting such obligations, You may act only
+   on Your own behalf and on Your sole responsibility, not on behalf
+   of any other Contributor, and only if You agree to indemnify,
+   defend, and hold each Contributor harmless for any liability
+   incurred by, or claims asserted against, such Contributor by reason
+   of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   Copyright 2025 BORANN CHANRATHNAK
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

pyxsql-1.0.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+xsql

xsql/__init__.py

@@ -0,0 +1,120 @@
+"""Python interface for XSQL query execution with safety-first defaults."""
+
+from __future__ import annotations
+
+from typing import Any, Dict, Optional
+
+from ._loader import load_html_source
+from ._security import FetchPolicy
+from ._summary import summarize_document
+from ._types import Document, ExportSink, QueryResult, TableResult
+
+try:
+    from . import _core
+except Exception as exc:  # pragma: no cover - surfaced in import-time errors.
+    _core = None
+    _core_import_error = exc
+else:
+    _core_import_error = None
+
+doc: Optional[Document] = None
+
+
+def _require_core() -> None:
+    if _core is None:
+        raise RuntimeError("xsql native module is unavailable") from _core_import_error
+
+
+def load(
+    source: Any,
+    *,
+    base_dir: Optional[str] = None,
+    allow_network: bool = False,
+    allow_private_network: bool = False,
+    timeout: int = 10,
+    max_bytes: int = 5_000_000,
+) -> Document:
+    """Loads HTML into a module-level Document for reuse across queries.
+
+    This function MUST be treated as not thread-safe because it mutates xsql.doc.
+    It performs IO for file/URL sources and enforces size/network limits.
+    """
+
+    policy = FetchPolicy(
+        allow_network=allow_network,
+        allow_private_network=allow_private_network,
+        timeout=timeout,
+        max_bytes=max_bytes,
+    )
+    html, origin = load_html_source(source, base_dir=base_dir, policy=policy)
+    document = Document(html=html, source=origin)
+    globals()["doc"] = document
+    return document
+
+
+def summarize(doc: Document, *, max_nodes_preview: int = 50) -> Dict[str, object]:
+    """Summarizes a document by tags and attribute keys without executing scripts.
+
+    The summary MUST avoid disclosing paths beyond the provided document source.
+    It performs parsing but does not execute or fetch external resources.
+    """
+
+    return summarize_document(doc, max_nodes_preview)
+
+
+def execute(
+    query: str,
+    *,
+    source: Any = None,
+    doc: Optional[Document] = None,
+    params: Optional[Dict[str, Any]] = None,
+    allow_network: bool = False,
+    base_dir: Optional[str] = None,
+    timeout: int = 10,
+    max_bytes: int = 5_000_000,
+    max_results: int = 10_000,
+) -> QueryResult:
+    """Executes an XSQL query against a document or source with safety limits.
+
+    The query MUST be executed without eval/exec and respects max_results limits.
+    It may read files or URLs when a source is provided and allow_network permits it.
+    """
+
+    _require_core()
+    if params:
+        raise ValueError("params are not supported by XSQL execution")
+    active = doc or globals().get("doc")
+    if active is None:
+        if source is None:
+            raise ValueError("No document loaded; provide doc or source")
+        policy = FetchPolicy(
+            allow_network=allow_network,
+            allow_private_network=False,
+            timeout=timeout,
+            max_bytes=max_bytes,
+        )
+        html, origin = load_html_source(source, base_dir=base_dir, policy=policy)
+        active = Document(html=html, source=origin)
+    raw = _core.execute_from_document(active.html, query)
+    rows = raw.get("rows", [])
+    tables = []
+    for table in raw.get("tables", []):
+        tables.append(TableResult(node_id=table["node_id"], rows=table["rows"]))
+    if len(rows) > max_results:
+        raise ValueError("Query result exceeds max_results")
+    total_table_rows = sum(len(table.rows) for table in tables)
+    if total_table_rows > max_results:
+        raise ValueError("Table result exceeds max_results")
+    export = raw.get("export_sink", {})
+    export_sink = ExportSink(kind=export.get("kind", "none"), path=export.get("path", ""))
+    return QueryResult(
+        columns=raw.get("columns", []),
+        rows=rows,
+        tables=tables,
+        to_list=raw.get("to_list", False),
+        to_table=raw.get("to_table", False),
+        export_sink=export_sink,
+    )
+
+
+__all__ = ["Document", "QueryResult", "TableResult", "ExportSink", "doc", "load", "summarize", "execute"]

xsql/_core.cpp

@@ -0,0 +1,86 @@
+#include <pybind11/pybind11.h>
+#include <pybind11/stl.h>
+
+#include "xsql/xsql.h"
+
+namespace py = pybind11;
+
+namespace {
+
+py::dict attributes_to_dict(const std::unordered_map<std::string, std::string>& attrs) {
+  py::dict out;
+  for (const auto& kv : attrs) {
+    out[py::str(kv.first)] = py::str(kv.second);
+  }
+  return out;
+}
+
+py::object field_value(const xsql::QueryResultRow& row, const std::string& field) {
+  if (field == "node_id") return py::int_(row.node_id);
+  if (field == "count") return py::int_(row.node_id);
+  if (field == "tag") return py::str(row.tag);
+  if (field == "text") return py::str(row.text);
+  if (field == "inner_html") return py::str(row.inner_html);
+  if (field == "parent_id") {
+    if (row.parent_id.has_value()) return py::int_(*row.parent_id);
+    return py::none();
+  }
+  if (field == "source_uri") return py::str(row.source_uri);
+  if (field == "attributes") return attributes_to_dict(row.attributes);
+  auto it = row.attributes.find(field);
+  if (it == row.attributes.end()) return py::none();
+  return py::str(it->second);
+}
+
+py::dict row_to_dict(const xsql::QueryResultRow& row, const std::vector<std::string>& columns) {
+  py::dict out;
+  for (const auto& col : columns) {
+    out[py::str(col)] = field_value(row, col);
+  }
+  return out;
+}
+
+}  // namespace
+
+PYBIND11_MODULE(_core, m) {
+  m.doc() = "Native bindings for XSQL query execution.";
+
+  m.def("execute_from_document",
+        [](const std::string& html, const std::string& query) {
+          xsql::QueryResult result = xsql::execute_query_from_document(html, query);
+          py::dict out;
+          out["columns"] = result.columns;
+          py::list rows;
+          for (const auto& row : result.rows) {
+            rows.append(row_to_dict(row, result.columns));
+          }
+          out["rows"] = rows;
+          py::list tables;
+          for (const auto& table : result.tables) {
+            py::dict table_obj;
+            table_obj["node_id"] = table.node_id;
+            table_obj["rows"] = table.rows;
+            tables.append(table_obj);
+          }
+          out["tables"] = tables;
+          out["to_list"] = result.to_list;
+          out["to_table"] = result.to_table;
+          py::dict export_sink;
+          switch (result.export_sink.kind) {
+            case xsql::QueryResult::ExportSink::Kind::Csv:
+              export_sink["kind"] = "csv";
+              break;
+            case xsql::QueryResult::ExportSink::Kind::Parquet:
+              export_sink["kind"] = "parquet";
+              break;
+            default:
+              export_sink["kind"] = "none";
+              break;
+          }
+          export_sink["path"] = result.export_sink.path;
+          out["export_sink"] = export_sink;
+          return out;
+        },
+        py::arg("html"),
+        py::arg("query"));
+}

xsql/_loader.py

@@ -0,0 +1,147 @@
+from __future__ import annotations
+
+import os
+import pathlib
+import re
+import urllib.request
+from html.parser import HTMLParser
+from typing import Optional, Tuple, Union
+from urllib.error import HTTPError, URLError
+
+from ._security import FetchPolicy, apply_redirect, is_url, normalize_path, validate_url_target
+
+_HTML_HINT = re.compile(r"<[^>]+>")
+_MAX_NODES = 100_000
+_ALLOWED_CONTENT_TYPES = {
+    "text/html",
+    "application/xhtml+xml",
+    "application/xml",
+    "text/xml",
+}
+
+
+class _NodeCountingParser(HTMLParser):
+    """Counts HTML start tags to cap parser growth before execution."""
+
+    def __init__(self, max_nodes: int) -> None:
+        super().__init__(convert_charrefs=True)
+        self.max_nodes = max_nodes
+        self.count = 0
+
+    def handle_starttag(self, tag: str, attrs) -> None:
+        self.count += 1
+        if self.count > self.max_nodes:
+            raise ValueError("HTML exceeds maximum node limit")
+
+
+class _NoRedirect(urllib.request.HTTPRedirectHandler):
+    """Disables automatic redirect handling so each hop can be validated."""
+
+    def redirect_request(self, req, fp, code, msg, headers, newurl):
+        return None
+
+
+def _enforce_max_nodes(html: str, max_nodes: int) -> None:
+    parser = _NodeCountingParser(max_nodes)
+    parser.feed(html)
+
+
+def _read_bytes_limited(path: str, max_bytes: int) -> bytes:
+    size = os.path.getsize(path)
+    if size > max_bytes:
+        raise ValueError("File exceeds maximum allowed size")
+    with open(path, "rb") as handle:
+        data = handle.read(max_bytes + 1)
+    if len(data) > max_bytes:
+        raise ValueError("File exceeds maximum allowed size")
+    return data
+
+
+def _decode_html(data: bytes) -> str:
+    return data.decode("utf-8", errors="replace")
+
+
+def _validate_content_type(content_type: Optional[str]) -> None:
+    if not content_type:
+        return
+    content_main = content_type.split(";", 1)[0].strip().lower()
+    if content_main not in _ALLOWED_CONTENT_TYPES:
+        raise ValueError("Unsupported content-type for HTML fetch")
+
+
+def _fetch_url(url: str, policy: FetchPolicy) -> Tuple[str, str]:
+    if not policy.allow_network:
+        raise ValueError("Network access is disabled by default")
+    validate_url_target(url, policy.allow_private_network)
+    current = url
+    opener = urllib.request.build_opener(_NoRedirect)
+    for _ in range(policy.max_redirects + 1):
+        try:
+            request = urllib.request.Request(current, headers={"User-Agent": "xsql-python/1.0"})
+            with opener.open(request, timeout=policy.timeout) as response:
+                if 300 <= response.status < 400:
+                    location = response.headers.get("Location")
+                    if not location:
+                        raise ValueError("Redirect response missing Location header")
+                    current = apply_redirect(current, location)
+                    validate_url_target(current, policy.allow_private_network)
+                    continue
+                _validate_content_type(response.headers.get("Content-Type"))
+                data = response.read(policy.max_bytes + 1)
+                if len(data) > policy.max_bytes:
+                    raise ValueError("Downloaded HTML exceeds max_bytes")
+                return _decode_html(data), current
+        except HTTPError as err:
+            if 300 <= err.code < 400:
+                location = err.headers.get("Location")
+                if not location:
+                    raise ValueError("Redirect response missing Location header") from err
+                current = apply_redirect(current, location)
+                validate_url_target(current, policy.allow_private_network)
+                continue
+            raise ValueError(f"HTTP error {err.code}") from err
+        except URLError as err:
+            raise ValueError("Failed to fetch URL") from err
+    raise ValueError("Too many redirects")
+
+
+def load_html_source(
+    source: Union[str, bytes, pathlib.Path],
+    *,
+    base_dir: Optional[str],
+    policy: FetchPolicy,
+) -> Tuple[str, str]:
+    """Loads HTML from a local path, URL, or raw HTML string."""
+
+    if isinstance(source, bytes):
+        if len(source) > policy.max_bytes:
+            raise ValueError("HTML exceeds maximum allowed size")
+        html = _decode_html(source)
+        _enforce_max_nodes(html, _MAX_NODES)
+        return html, "document"
+
+    if isinstance(source, pathlib.Path):
+        source = str(source)
+
+    if not isinstance(source, str):
+        raise TypeError("source must be str, bytes, or Path")
+
+    if is_url(source):
+        html, final_url = _fetch_url(source, policy)
+        _enforce_max_nodes(html, _MAX_NODES)
+        return html, final_url
+
+    if os.path.exists(source):
+        path = normalize_path(source, base_dir)
+        data = _read_bytes_limited(path, policy.max_bytes)
+        html = _decode_html(data)
+        _enforce_max_nodes(html, _MAX_NODES)
+        return html, source
+
+    if _HTML_HINT.search(source):
+        if len(source.encode("utf-8", errors="replace")) > policy.max_bytes:
+            raise ValueError("HTML exceeds maximum allowed size")
+        _enforce_max_nodes(source, _MAX_NODES)
+        return source, "document"
+
+    raise ValueError("Source is ambiguous; pass bytes for raw HTML")

xsql/_security.py

@@ -0,0 +1,79 @@
+from __future__ import annotations
+
+import ipaddress
+import os
+import socket
+from dataclasses import dataclass
+from typing import Iterable, Optional, Tuple
+from urllib.parse import urlparse, urljoin
+
+
+@dataclass(frozen=True)
+class FetchPolicy:
+    """Defines network and resource limits for fetching HTML content."""
+
+    allow_network: bool
+    allow_private_network: bool
+    timeout: int
+    max_bytes: int
+    max_redirects: int = 3
+
+
+_PRIVATE_NETS = [
+    ipaddress.ip_network("127.0.0.0/8"),
+    ipaddress.ip_network("10.0.0.0/8"),
+    ipaddress.ip_network("172.16.0.0/12"),
+    ipaddress.ip_network("192.168.0.0/16"),
+    ipaddress.ip_network("169.254.0.0/16"),
+    ipaddress.ip_network("::1/128"),
+    ipaddress.ip_network("fc00::/7"),
+    ipaddress.ip_network("fe80::/10"),
+]
+
+
+def is_url(source: str) -> bool:
+    """Detects http/https URLs to avoid ambiguous HTML interpretation."""
+
+    parsed = urlparse(source)
+    return parsed.scheme in {"http", "https"} and bool(parsed.netloc)
+
+
+def resolve_host(host: str) -> Iterable[ipaddress._BaseAddress]:
+    """Resolves hostnames to IP addresses for SSRF filtering."""
+
+    infos = socket.getaddrinfo(host, None)
+    for family, _, _, _, sockaddr in infos:
+        if family == socket.AF_INET:
+            yield ipaddress.ip_address(sockaddr[0])
+        elif family == socket.AF_INET6:
+            yield ipaddress.ip_address(sockaddr[0])
+
+
+def validate_url_target(url: str, allow_private: bool) -> None:
+    """Blocks localhost/private targets unless explicitly allowed."""
+
+    parsed = urlparse(url)
+    if parsed.scheme not in {"http", "https"}:
+        raise ValueError("Only http/https URLs are allowed")
+    if not parsed.hostname:
+        raise ValueError("URL must include a hostname")
+    for addr in resolve_host(parsed.hostname):
+        if any(addr in net for net in _PRIVATE_NETS) and not allow_private:
+            raise ValueError("URL points to a private or localhost address")
+
+
+def normalize_path(path: str, base_dir: Optional[str]) -> str:
+    """Normalizes and confines file paths when base_dir is provided."""
+
+    real = os.path.realpath(path)
+    if base_dir:
+        base = os.path.realpath(base_dir)
+        if os.path.commonpath([real, base]) != base:
+            raise ValueError("Path escapes the configured base_dir")
+    return real
+
+
+def apply_redirect(url: str, location: str) -> str:
+    """Resolves redirect targets while preserving relative locations."""
+
+    return urljoin(url, location)

xsql/_summary.py

@@ -0,0 +1,38 @@
+from __future__ import annotations
+
+from collections import Counter
+from html.parser import HTMLParser
+from typing import Dict, List, Tuple
+
+from ._types import Document
+
+
+class _SummaryParser(HTMLParser):
+    """Collects tag and attribute statistics without executing scripts."""
+
+    def __init__(self) -> None:
+        super().__init__(convert_charrefs=True)
+        self.tag_counts: Counter[str] = Counter()
+        self.attr_counts: Counter[str] = Counter()
+        self.total_nodes = 0
+
+    def handle_starttag(self, tag: str, attrs) -> None:
+        self.total_nodes += 1
+        self.tag_counts[tag] += 1
+        for key, _ in attrs:
+            if key:
+                self.attr_counts[key] += 1
+
+
+def summarize_document(doc: Document, max_nodes_preview: int) -> Dict[str, object]:
+    """Produces a deterministic summary of tag and attribute usage."""
+
+    parser = _SummaryParser()
+    parser.feed(doc.html)
+    tags = parser.tag_counts.most_common(max_nodes_preview)
+    attrs = parser.attr_counts.most_common(max_nodes_preview)
+    return {
+        "total_nodes": parser.total_nodes,
+        "tag_counts": tags,
+        "attribute_keys": attrs,
+    }

xsql/_types.py

@@ -0,0 +1,40 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any, Dict, List, Optional
+
+
+@dataclass(frozen=True)
+class Document:
+    """Represents a parsed HTML document snapshot for deterministic queries."""
+
+    html: str
+    source: str
+
+
+@dataclass(frozen=True)
+class ExportSink:
+    """Captures export intent attached to a query result."""
+
+    kind: str
+    path: str
+
+
+@dataclass(frozen=True)
+class TableResult:
+    """Holds rows extracted from an HTML <table> node."""
+
+    node_id: int
+    rows: List[List[Optional[str]]]
+
+
+@dataclass(frozen=True)
+class QueryResult:
+    """Carries rows/tables plus metadata from executing an XSQL query."""
+
+    columns: List[str]
+    rows: List[Dict[str, Any]]
+    tables: List[TableResult]
+    to_list: bool
+    to_table: bool
+    export_sink: ExportSink