Skip to content

Commit 77ee931

Browse files
lexakimovlexakimov
authored
Merge pull request #12 from lexakimov/feature
Improve documentation
2 parents 0a747ee + fc6a972 commit 77ee931

File tree

10 files changed

+1462
-410
lines changed

10 files changed

+1462
-410
lines changed

‎CONFIGURATION.md‎

Lines changed: 601 additions & 0 deletions
Large diffs are not rendered by default.

‎CONFIGURATION_RU.md‎

Lines changed: 601 additions & 0 deletions
Large diffs are not rendered by default.

‎README.md‎

Lines changed: 88 additions & 203 deletions
Original file line numberDiff line numberDiff line change
@@ -4,6 +4,7 @@
44
- [English 🇺🇸](README.md)
55

66
Generates XML documents based on XSD schemas with the ability to customize data through a YAML configuration file.
7+
78
Simplifies the creation of test or demonstration XML data for complex schemas.
89

910
## Features
@@ -21,82 +22,30 @@ Simplifies the creation of test or demonstration XML data for complex schemas.
2122
pip install xmlgenerator
2223
```
2324

24-
### Build from source
25-
26-
1. **Clone the repository:**
27-
```bash
28-
git clone https://github.com/lexakimov/xmlgenerator.git
29-
cd xmlgenerator
30-
```
31-
32-
2. **Create and activate a virtual environment (recommended):**
33-
```bash
34-
python -m venv .venv
35-
```
36-
* **For Linux/macOS:**
37-
```bash
38-
source .venv/bin/activate
39-
```
40-
* **For Windows (Command Prompt/PowerShell):**
41-
```bash
42-
.\.venv\Scripts\activate
43-
```
44-
45-
3. **Install dependencies:**
46-
```bash
47-
pip install -r requirements.txt
48-
```
49-
50-
4.1. **Install the package:**
51-
```bash
52-
pip install .
53-
# or for development mode (code changes will be immediately reflected)
54-
# pip install -e .
55-
```
56-
57-
4.2. **Otherwise, build single executable:**
58-
```bash
59-
python build_native.py
60-
```
61-
62-
## CLI Usage
63-
64-
The main command to run the generator is `xmlgenerator`.
65-
66-
**Examples:**
67-
68-
- Generate XML from a single schema and print to console:
69-
```bash
70-
xmlgenerator path/to/your/schema.xsd
71-
```
25+
### Install executable file manually (linux)
7226

73-
- Generate XML from all schemas in a directory and save to the `output` folder using a configuration file:
74-
```bash
75-
xmlgenerator -c config.yml -o output/ path/to/schemas/
76-
```
77-
78-
- Generate XML from a specific schema, save to a file with pretty formatting and windows-1251 encoding:
79-
```bash
80-
xmlgenerator -o output.xml -p -e windows-1251 path/to/your/schema.xsd
81-
```
82-
83-
- Generate XML with validation disabled:
84-
```bash
85-
xmlgenerator -v none path/to/your/schema.xsd
86-
```
27+
```bash
28+
curl -LO https://github.com/lexakimov/xmlgenerator/releases/download/v0.5.3/xmlgenerator-linux-amd64
29+
chmod +x xmlgenerator-linux-amd64
30+
sudo install xmlgenerator-linux-amd64 /usr/local/bin/xmlgenerator
31+
```
8732

88-
**Install shell completions:**
33+
### Install shell completions (linux)
8934

9035
```shell
9136
# also available: zsh, tcsh
9237
xmlgenerator -C bash | sudo tee /etc/bash_completion.d/xmlgenerator
9338
```
9439

95-
**Detailed CLI Usage:**
40+
## Usage
41+
42+
The generator command is `xmlgenerator`
43+
44+
**Flags and parameters:**
9645

9746
```
98-
usage: xmlgenerator [-h] [-c <config.yml>] [-o <output.xml>] [-p] [-v <validation>] [-ff] [-e <encoding>]
99-
[--seed <seed>] [-d] [-V]
47+
usage: xmlgenerator [-h] [-c <config.yml>] [-l <locale>] [-o <output.xml>] [-p] [-v <validation>] [-ff] [-e <encoding>]
48+
[-s <seed>] [-d] [-V] [-C <shell>]
10049
xsd [xsd ...]
10150
10251
Generates XML documents from XSD schemas
@@ -106,150 +55,46 @@ positional arguments:
10655
10756
options:
10857
-h, --help show this help message and exit
109-
-c, --config <config.yml> pass yaml configuration file
110-
-l, --locale <locale> randomizer locale (default: en_US)
111-
-o, --output <output.xml> save output to dir or file
112-
-p, --pretty prettify output XML
113-
-v, --validation <validation> validate generated XML document (none, schema, schematron, default is schema)
114-
-ff, --fail-fast terminate execution on validation error (default is true)
115-
-e, --encoding <encoding> output XML encoding (utf-8, windows-1251, default is utf-8)
116-
-s, --seed <seed> set randomization seed
58+
-c, --config <config.yml> pass a YAML configuration file
59+
-l, --locale <locale> locale for the randomizer (default: en_US)
60+
-o, --output <output.xml> save the output to a directory or file
61+
-p, --pretty prettify the output XML
62+
-v, --validation <validation> validate the generated XML document (none, schema, schematron; default: schema)
63+
-ff, --fail-fast terminate execution on a validation error (default: true)
64+
-e, --encoding <encoding> the output XML encoding (utf-8, windows-1251; default: utf-8)
65+
-s, --seed <seed> set the randomization seed
11766
-d, --debug enable debug mode
118-
-V, --version shows current version
119-
-C, --completion <shell> print shell completion script (bash, zsh, tcsh)
67+
-V, --version show the current version
68+
-C, --completion <shell> print a shell completion script (bash, zsh, tcsh)
12069
```
12170

122-
## Configuration
71+
**Examples:**
12372

124-
The generator can be configured using a YAML file passed via the `-c` or `--config` option.
73+
- Generate XML from a single schema and print to console:
74+
```bash
75+
xmlgenerator path/to/your/schema.xsd
76+
```
12577

126-
**Configuration File Structure:**
127-
128-
```yaml
129-
# Global settings (apply to all schemas)
130-
global:
131-
132-
# Regular expression to extract a substring from the source xsd schema filename.
133-
# The extracted substring can be used via the `source_extracted` function.
134-
# The regular expression must contain the group `extracted`.
135-
# Default value: `(?P<extracted>.*).(xsd|XSD)` (extracts the filename without extension).
136-
source_filename: ...
137-
138-
# Filename template for saving the generated document.
139-
# Default value: `{{ source_extracted }}_{{ uuid }}` (xsd schema filename + random UUID)
140-
output_filename: ...
141-
142-
# Random value generator settings
143-
randomization:
144-
# Probability of adding optional elements (0.0-1.0)
145-
# Default value: 0.5
146-
probability: 1
147-
# Limit for the minimal number of elements
148-
min_occurs: 0
149-
# Limit for the maximum number of elements
150-
max_occurs: 5
151-
# Minimum string length
152-
min_length: 5
153-
# Maximum string length
154-
max_length: 20
155-
# Minimum numeric value
156-
min_inclusive: 10
157-
# Maximum numeric value
158-
max_inclusive: 1000000
159-
160-
# Override generated values for tags and attributes.
161-
# Key - string or regular expression to match the tag/attribute name.
162-
# Value - string with optional use of placeholders:
163-
# `{{ function }}` - substitutes the value provided by the predefined function.
164-
# `{{ function | modifier }}` - same, but with a modifier [ global | local ].
165-
# - `global` - a single value will be used along all generation.
166-
# - `local` - a single value will be used in context of current document.
167-
#
168-
# The list of available functions is below.
169-
# The order of entries matters; the first matching override will be selected.
170-
# Key matching is case-insensitive.
171-
value_override:
172-
name_regexp_1: "static value"
173-
name_regexp_2: "{{ function_call }}"
174-
"name_regexp_\d": "static-text-and-{{ function_call }}"
175-
name: "static-text-and-{{ function_call }}-{{ another_function_call }}"
176-
177-
# Extend/override global settings for specific files.
178-
# Key - string or regular expression to match the xsd filename(s).
179-
# The order of entries matters; the first matching override will be selected.
180-
# Key matching is case-insensitive.
181-
specific:
182-
# Each value can have the same set of parameters as the global section
183-
"SCHEM.*":
184-
# for schemas named "SCHEM.*", xml document names will only contain UUIDv4 + '.xml'
185-
output_filename: "{{ uuid }}"
186-
# Random value generator settings for schemas named "SCHEM.*"
187-
randomization:
188-
# for schemas named "SCHEM.*", the probability of adding optional elements will be 30%
189-
probability: 0.3
190-
value_override:
191-
# override the value set by the global configuration
192-
name_regexp_1: "static value"
193-
# reset overrides for tags/attributes containing 'name' set by the global configuration
194-
name:
195-
```
78+
- Generate XML from all schemas in a directory and save to the `output` folder using a configuration file:
79+
```bash
80+
xmlgenerator -c config.yml -o output/ path/to/schemas/
81+
```
19682

197-
Configuration Priority:
198-
199-
- specific settings
200-
- global settings
201-
- default settings
202-
203-
### Placeholder Functions
204-
205-
In the `value_override` sections, you can specify either a string value or special placeholders:
206-
207-
- `{{ function }}` - Substitutes the value provided by the predefined function.
208-
- `{{ function | modifier }}` - Same, but with a modifier `[ global | local ]`, where:
209-
- `global`: The function will generate and use *the same single value* throughout the *entire generation process*
210-
for all documents.
211-
- `local`: The function will generate and use *the same single value* within the scope of *a single generated
212-
document*.
213-
- No modifier: A new value is generated each time the function is called.
214-
215-
**List of Placeholder Functions:**
216-
217-
| Function | Description |
218-
|------------------------------------|------------------------------------------------------------------------------------------------------------|
219-
| `source_filename` | Filename of the source xsd schema with extension (e.g., `schema.xsd`) |
220-
| `source_extracted` | String extracted from the source xsd filename using the regex specified in `source_filename_extract_regex` |
221-
| `output_filename` | String described by the `output_filename_template` configuration parameter |
222-
| `uuid` | Random UUIDv4 |
223-
| `regex("pattern")` | Random string value matching the specified regular expression |
224-
| `any('A', "B", C)` | Random value from enumeration |
225-
| `number(A, B)` | Random number between A and B |
226-
| `date("2010-01-01", "2025-01-01")` | Random date within the specified range |
227-
| `last_name` | Last Name |
228-
| `first_name` | First Name |
229-
| `middle_name` | Middle Name |
230-
| `address_text` | Address |
231-
| `administrative_unit` | Administrative Unit (e.g., District) |
232-
| `house_number` | House Number |
233-
| `city_name` | City Name |
234-
| `postcode` | Postal Code |
235-
| `company_name` | Company Name |
236-
| `bank_name` | Bank Name |
237-
| `phone_number` | Phone Number |
238-
| `inn_fl` | Individual Taxpayer Number (Physical Person) |
239-
| `inn_ul` | Taxpayer Identification Number (Legal Entity) |
240-
| `ogrn_ip` | Primary State Registration Number (Individual Entrepreneur) |
241-
| `ogrn_fl` | Primary State Registration Number (Physical Person) |
242-
| `kpp` | Reason Code for Registration |
243-
| `snils_formatted` | SNILS (Personal Insurance Account Number) in the format `123-456-789 90` |
244-
| `email` | Random email address |
245-
246-
**Configuration Examples:**
247-
248-
```yaml
249-
# TODO Add configuration examples.
250-
```
83+
- Generate XML from a specific schema, save to a file with pretty formatting and windows-1251 encoding:
84+
```bash
85+
xmlgenerator -o output.xml -p -e windows-1251 path/to/your/schema.xsd
86+
```
25187

252-
---
88+
- Generate XML with validation disabled:
89+
```bash
90+
xmlgenerator -v none path/to/your/schema.xsd
91+
```
92+
93+
## Configuration
94+
95+
The generator can be configured using a YAML file passed via the `-c` or `--config` option.
96+
97+
Description and examples of configuration are in [CONFIGURATION](./CONFIGURATION.md).
25398

25499
## Validation
255100

@@ -265,6 +110,46 @@ To disable validation, use the flag `-v none` or `--validation none`.
265110

266111
Contributions are welcome! Please open an issue or submit a pull request on GitHub.
267112

113+
### Build from source
114+
115+
1. **Clone the repository:**
116+
```bash
117+
git clone https://github.com/lexakimov/xmlgenerator.git
118+
cd xmlgenerator
119+
```
120+
121+
2. **Create and activate a virtual environment (recommended):**
122+
```bash
123+
python -m venv .venv
124+
```
125+
* **For Linux/macOS:**
126+
```bash
127+
source .venv/bin/activate
128+
```
129+
* **For Windows (Command Prompt/PowerShell):**
130+
```bash
131+
.\.venv\Scripts\activate
132+
```
133+
134+
3. **Install dependencies:**
135+
```bash
136+
pip install -r requirements.txt
137+
```
138+
139+
4.1. **Install the package:**
140+
141+
```bash
142+
pip install .
143+
# or for development mode (code changes will be immediately reflected)
144+
# pip install -e .
145+
```
146+
147+
4.2. **Otherwise, build single executable:**
148+
149+
```bash
150+
python build_native.py
151+
```
152+
268153
### Project Structure
269154

270155
- `xmlgenerator/` - main project code

0 commit comments

Comments
 (0)