# Python Reference Variables `refvars`
This repository contains but two simple but extremely useful Python class, `new` and `Reference`.
**ALSO:** [C Pointers in Python](#c-pointers-in-python).
This holy grail of simple python hacks, `refvars` provides a convenient way to work with references to objects.
It allows you to set and get the value of the reference using simple `get` and `set` methods.
## Usage
To use the `refvars` class, simply import it into your Python script:
```python
import refvars
```
Then use `new` to create a reference to an object:
```python
# Create a reference.
ref = refvars.new[int](0).get_ref()
```
**Note**: that `new` will run a variety of runtime checks to ensure that the reference is being used correctly.
* The way these checks work is by very basic checking of source code.
* This can lead to some problems when trying to open your source code file with `inspect` module.
To fix this:
```python
refvars.disable_runtime_usage_checks()
```
Now, you can use the `Reference` to `get` and `set` the value of the reference:
```python
# To ensure that the initial value does actually change.
print(ref.get()) # 0
# If we want a function to modify the reference, we can pass the reference to the function.
def modify_reference(ref:"refvars.Reference[int]"):
ref.set(1)
modify_reference(ref)
print(ref.get()) # 1
```
## Installation
To install the `refvars`, use pip:
```bash
pip install refvars
```
## C Pointers in Python
Yes, you heard it right. You can use `refvars` to access memory created by C code in Python.
```python
from refvars import alloc
```
The `alloc` is much the same to the `new` class. But instead we use `safe_access(< your cb >)` to safely access the memory.
```python
from refvars import alloc, Pointer
def callback(ptr:"Pointer") -> None:
print(f"Address: {ptr.address}")
# We even have basic error handling to stop you from writing more than 64 bytes.
more_than_64 = b"X" * 65
ptr.write(more_than_64) # This will raise an error.
# This allocates 64 bytes of memory.
# Your callback will be called with a `Pointer` object as the only argument.
# On function return, the memory will be freed.
# Meaning that we are (hopefully) safe from memory leaks and cyber attacks.
alloc(64).safe_access(callback)
```
A working version you can use is:
```python
from refvars import alloc, Pointer
def callback(ptr:"Pointer") -> None:
print(f"Address: {ptr.address}")
data = b"Hello, World!"
ptr.write(data)
print(ptr.read(len(data))) # b"Hello, World!"
alloc(1024).safe_access(callback)
```
## Confirmed versions of Python
* [x] 3.11 - Works perfectly on the old version (before c pointer update).
* [x] 3.12 - Works perfectly.
## License
Covered under the GNU General Public License v2.0.
## V0.7 released on 29th/5/2024
Redesign and added accessing c pointers from Python.
Raw data
{
"_id": null,
"home_page": null,
"name": "refvars",
"maintainer": null,
"docs_url": null,
"requires_python": null,
"maintainer_email": null,
"keywords": "python, reference, variables, pointers, output, return, types, reference types, refvars",
"author": "matrikater (Joel C. Watson)",
"author_email": "matrikater@matriko.xyz",
"download_url": null,
"platform": null,
"description": "# Python Reference Variables `refvars`\r\n\r\nThis repository contains but two simple but extremely useful Python class, `new` and `Reference`.\r\n\r\n**ALSO:** [C Pointers in Python](#c-pointers-in-python).\r\n\r\nThis holy grail of simple python hacks, `refvars` provides a convenient way to work with references to objects.\r\nIt allows you to set and get the value of the reference using simple `get` and `set` methods.\r\n\r\n## Usage\r\n\r\nTo use the `refvars` class, simply import it into your Python script:\r\n\r\n```python\r\nimport refvars\r\n```\r\n\r\nThen use `new` to create a reference to an object:\r\n\r\n```python\r\n# Create a reference.\r\nref = refvars.new[int](0).get_ref()\r\n```\r\n\r\n**Note**: that `new` will run a variety of runtime checks to ensure that the reference is being used correctly.\r\n\r\n* The way these checks work is by very basic checking of source code.\r\n* This can lead to some problems when trying to open your source code file with `inspect` module.\r\n\r\nTo fix this:\r\n\r\n```python\r\nrefvars.disable_runtime_usage_checks()\r\n```\r\n\r\nNow, you can use the `Reference` to `get` and `set` the value of the reference:\r\n\r\n```python\r\n# To ensure that the initial value does actually change.\r\nprint(ref.get()) # 0\r\n\r\n# If we want a function to modify the reference, we can pass the reference to the function.\r\ndef modify_reference(ref:\"refvars.Reference[int]\"):\r\n ref.set(1)\r\n\r\nmodify_reference(ref)\r\n\r\nprint(ref.get()) # 1\r\n```\r\n\r\n## Installation\r\n\r\nTo install the `refvars`, use pip:\r\n\r\n```bash\r\npip install refvars\r\n```\r\n\r\n## C Pointers in Python\r\n\r\nYes, you heard it right. You can use `refvars` to access memory created by C code in Python.\r\n\r\n```python\r\nfrom refvars import alloc\r\n```\r\n\r\nThe `alloc` is much the same to the `new` class. But instead we use `safe_access(< your cb >)` to safely access the memory.\r\n\r\n```python\r\nfrom refvars import alloc, Pointer\r\n\r\ndef callback(ptr:\"Pointer\") -> None:\r\n\tprint(f\"Address: {ptr.address}\")\r\n\t# We even have basic error handling to stop you from writing more than 64 bytes.\r\n\tmore_than_64 = b\"X\" * 65\r\n\tptr.write(more_than_64) # This will raise an error.\r\n\t\r\n# This allocates 64 bytes of memory.\r\n# Your callback will be called with a `Pointer` object as the only argument.\r\n# On function return, the memory will be freed.\r\n# Meaning that we are (hopefully) safe from memory leaks and cyber attacks.\r\nalloc(64).safe_access(callback)\r\n```\r\n\r\nA working version you can use is:\r\n\r\n```python\r\nfrom refvars import alloc, Pointer\r\n\r\ndef callback(ptr:\"Pointer\") -> None:\r\n\tprint(f\"Address: {ptr.address}\")\r\n\tdata = b\"Hello, World!\"\r\n\tptr.write(data)\r\n\tprint(ptr.read(len(data))) # b\"Hello, World!\"\r\n\r\nalloc(1024).safe_access(callback)\r\n```\r\n\r\n## Confirmed versions of Python\r\n\r\n* [x] 3.11 - Works perfectly on the old version (before c pointer update).\r\n* [x] 3.12 - Works perfectly.\r\n\r\n## License\r\n\r\nCovered under the GNU General Public License v2.0.\r\n\r\n## V0.7 released on 29th/5/2024\r\n\r\nRedesign and added accessing c pointers from Python.\r\n",
"bugtrack_url": null,
"license": null,
"summary": "Solving one of Python's biggest problems. Reference types (output variables) are not implemented.",
"version": "0.7",
"project_urls": null,
"split_keywords": [
"python",
" reference",
" variables",
" pointers",
" output",
" return",
" types",
" reference types",
" refvars"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "291af0355fd3eb80898db29f5be6aac8c4b0defcad46ab3afded993efcfb3871",
"md5": "676d319e673bca3bc4be2d335b214e5b",
"sha256": "cd2161580546d7e2b5e5b22a477b1931b6e4768bd4ba226157cb1132d707d096"
},
"downloads": -1,
"filename": "refvars-0.7-py3-none-any.whl",
"has_sig": false,
"md5_digest": "676d319e673bca3bc4be2d335b214e5b",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": null,
"size": 88506,
"upload_time": "2024-05-29T06:58:05",
"upload_time_iso_8601": "2024-05-29T06:58:05.606429Z",
"url": "https://files.pythonhosted.org/packages/29/1a/f0355fd3eb80898db29f5be6aac8c4b0defcad46ab3afded993efcfb3871/refvars-0.7-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-05-29 06:58:05",
"github": false,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"lcname": "refvars"
}
JSON