Skip to content

Commit 991cd6b

Browse files
DefinetlyNotAIDefinetlyNotAI
committed
Update README.md: improve wheel file creation instructions and enhance project structure details
1 parent 18f79a2 commit 991cd6b

File tree

1 file changed

+96
-51
lines changed

1 file changed

+96
-51
lines changed

‎README.md‎

Lines changed: 96 additions & 51 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,26 @@
1-
# Project Overview
1+
<div align="center">
2+
<h1>PyCTools</h1>
3+
<img src="https://img.shields.io/badge/license-MIT-blue" alt="License" />
4+
<img src="https://img.shields.io/badge/platform-Windows-lightgray" alt="Platform" />
5+
<img src="https://img.shields.io/github/languages/top/DefinetlyNotAI/PyCTools" alt="Languages" />
6+
<img src="https://img.shields.io/github/v/tag/DefinetlyNotAI/PyCTools" alt="Version" />
7+
</div>
8+
9+
> [!NOTE]
10+
> There are multiple ways to install the pyCTools library!
11+
>
12+
> * **Manual installation:**
13+
>
14+
> 1. Clone the repository and build the DLLs yourself.
15+
> 2. Run the following to create the wheel file:
16+
> ```bash
17+
> cd tools python setup.py bdist_wheel
18+
> ```
19+
> 3. The setup script will show you how to install the package locally with pip and how to create a virtual environment for testing.
20+
> * **Automatic installation:**
21+
> Go to the [releases page](https://github.com/DefinetlyNotAI/PyCTools/releases) and select the version you wish to install, and click on it, then copy the top `pip` command that will allow you to install it
22+
> [Auto installation support from v0.2.0-beta and above]
23+
224
325
This project provides a cross-language toolkit for Windows process inspection and hardware random number generation, with both Python and C components. It includes:
426
@@ -7,65 +29,88 @@ This project provides a cross-language toolkit for Windows process inspection an
729
- **Example Python scripts**: Demonstrate usage of the library.
830
- **PowerShell build helper**: Automates DLL compilation for x86/x64.
931
32+
> [!IMPORTANT]
33+
> To get the `dist` binary folder, choose **one** of the following options:
34+
>
35+
> | Method | Description | Requirements |
36+
> |--------------------------|--------------------------------------------------------------------------------------------------------------|-----------------------------------------------------|
37+
> | Manual Build | Compile the binaries yourself using `cl.exe` or similar toolchains | Microsoft Visual Studio with MSVC installed |
38+
> | Auto Build Script | Run the [`tool/compilerHelper.ps1`](tool/compilerHelper.ps1) PowerShell script | Visual Studio Build Tools + PowerShell |
39+
> | Prebuilt Release Archive | Download precompiled binaries from the [releases page](https://github.com/DefinetlyNotAI/PyCTools/releases/) | None, make sure to use the latest available version |
40+
>
41+
> No matter what you decide, do still read the important notice about the `dist` from the [release](https://github.com/DefinetlyNotAI/PyCTools/releases/) OR check the [Wiki](https://github.com/DefinetlyNotAI/PyCTools/wiki#dll-discovery-and-dist-directory) page about the DLL discovery explanation.
42+
1043
## Directory Structure
1144
12-
```
13-
example/
14-
pyCTools/
15-
hwrng.py # Python wrapper for hardware RNG DLL
16-
processInspect.py # Python wrapper for process inspection DLL
17-
hwrng_example.py # Example: hardware RNG usage
18-
process_inspect_example.py # Example: process metrics usage
19-
src/
20-
hRng.c # C source for hardware RNG DLL
21-
processInspect.c # C source for process inspection DLL
22-
tool/
23-
compilerHelper.ps1 # PowerShell script to build DLLs for x86/x64
24-
dist/
25-
x64/ # Compiled DLLs for 64-bit
26-
x86/ # Compiled DLLs for 32-bit
27-
```
28-
29-
## Building the DLLs
30-
31-
1. Open PowerShell and run `tool/compilerHelper.ps1`.
32-
2. Select which `.c` files to compile.
33-
3. The script will build both x86 and x64 DLLs and place them in `dist/x86` and `dist/x64`.
45+
<details>
46+
<summary>📁 Project Structure (click to expand)</summary>
47+
48+
root/
49+
├── dist/ # Release artifacts for distribution
50+
│ ├── rawBinaryZipped/ # Prebuilt binaries files (generated by `distributionHelper.ps1`)
51+
│ │ ├── bin.zip # Zipped prebuilt binaries
52+
│ │ └── bin.zip.sha256 # SHA256 checksum for `bin.zip`
53+
│ └── libraryWheel/ # Library wheel files (generated by `setup.py`)
54+
│ └── *.whl # Python wheel files for library distribution via pip
55+
│
56+
├── examples/ # Example Python scripts demonstrating usage
57+
│ ├── hwrng_example.py # Example: Hardware RNG usage
58+
│ ├── process_inspect_example.py # Example: Process inspection usage
59+
│ └── rng_tests/ # RNG test scripts and outputs
60+
│ ├── rng_output.bin # 10M bytes of RNG data (complexity 1, threaded)
61+
│ ├── Results.txt # Test results from `rng_test.py`
62+
│ ├── rng_test.py # Script to test hardware RNG
63+
│ └── generate_bin.py # Generates binary file from RNG
64+
│
65+
├── pyCTools/ # Python package (library code)
66+
│ ├── bin/ # Auto-generated folder containing compiled DLL binaries
67+
│ │ ├── x86/ # 32-bit DLL builds
68+
│ │ └── x64/ # 64-bit DLL builds
69+
│ ├── __init__.py # Package initializer
70+
│ ├── hwrng.py # Hardware RNG DLL wrapper
71+
│ ├── processInspect.py # Process inspection DLL wrapper
72+
│ └── _loadDLL.py # DLL loading logic used by wrappers
73+
│
74+
├── tool/ # Build and distribution tools
75+
│ ├── compilerHelper.ps1 # Compiles C code into DLLs
76+
│ └── distributionHelper.ps1 # Creates `bin.zip` and SHA256 checksum
77+
│
78+
├── src/ # C source code for DLLs
79+
│ ├── hRng.c # Hardware RNG implementation
80+
│ └── processInspect.c # Process inspection implementation
81+
│
82+
└── CMakeLists.txt # CMake build configuration (currently unused)
83+
84+
</details>
3485
3586
## Using the Python Library
3687
37-
- Place the `dist/` folder as a sibling to your Python scripts or as described in the wrappers.
38-
- Import and use `pyCTools.hwrng` or `pyCTools.processInspect` as shown in the examples.
39-
40-
## Example Usage
41-
42-
**Hardware RNG:**
43-
```python
44-
from pyCTools.hwrng import get_hardware_random_bytes
45-
rb = get_hardware_random_bytes(16)
46-
print(rb.hex())
47-
```
88+
- Place the `dist/` folder inside the `pyCTools` package directory.
89+
- Import and use `hwrng` or `processInspect` from `pyCTools`.
90+
- The library will automatically load the correct DLL based on your Python interpreter architecture (x86 or x64).
4891
49-
**Process Inspection:**
50-
```python
51-
from pyCTools.processInspect import ProcessMetrics
52-
metrics = ProcessMetrics()
53-
pid = 1234 # Target PID
54-
flags = ProcessMetrics.METRIC_WORKING_SET | ProcessMetrics.METRIC_CPU_USAGE
55-
snapshot = metrics.get_snapshot(pid, flags)
56-
print(snapshot)
57-
```
92+
> [!TIP]
93+
> Example usages for both modules in detail:
94+
>
95+
> #### Hardware RNG
96+
> Either check out the [example script](example/hwrng_example.py) or the [Wiki page](https://github.com/DefinetlyNotAI/PyCTools/wiki/Py-Documentation-‐-hwrng#methods)
97+
>
98+
> #### Process Inspection
99+
> Either check out the [example script](example/process_inspect_example.py) or the [Wiki page](https://github.com/DefinetlyNotAI/PyCTools/wiki/Py-Documentation-‐-processInspect#methods)
58100
59-
## DLL Discovery
101+
### DLL Info
60102
61-
The Python wrappers automatically search for the correct DLL in:
62-
- `./dist/{arch}/<dll>`
63-
- `../dist/{arch}/<dll>`
64-
- `../../dist/{arch}/<dll>`
103+
You can find all information in the [Wiki](https://github.com/DefinetlyNotAI/PyCTools/wiki#dll-discovery-and-bin-directory).
65104
66-
where `{arch}` is `x64` or `x86` depending on your Python interpreter.
105+
Details about building the DLLs can be found in more detail [here](https://github.com/DefinetlyNotAI/PyCTools/wiki#building-the-dlls)
67106
68-
## License
69107
70-
MIT or specify your license here.
108+
## Extra resources
71109
110+
> [!TIP]
111+
> Want to dive deeper into how everything works? Head over to the [PyCTools Wiki](https://github.com/DefinetlyNotAI/PyCTools/wiki) for detailed breakdowns of the key parts:
112+
>
113+
> • **DLL explanations**: learn how the DLLs are structured, discovered, and loaded
114+
> • **Python examples, wrappers, and usage**: practical code snippets and usage patterns in Python
115+
> • **C code explanation**: understand the underlying native implementation
116+
> • **Build and distribution**: how to compile, package, and distribute the libraries

0 commit comments

Comments
 (0)