sru-generator 1.0.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (41) hide show
  1. sru_generator-1.0.0/CHANGELOG.md +64 -0
  2. sru_generator-1.0.0/DISCLAIMER.md +62 -0
  3. sru_generator-1.0.0/LICENSE +21 -0
  4. sru_generator-1.0.0/MANIFEST.in +3 -0
  5. sru_generator-1.0.0/PKG-INFO +404 -0
  6. sru_generator-1.0.0/README.md +373 -0
  7. sru_generator-1.0.0/pyproject.toml +107 -0
  8. sru_generator-1.0.0/setup.cfg +4 -0
  9. sru_generator-1.0.0/sru_generator/__init__.py +214 -0
  10. sru_generator-1.0.0/sru_generator/amounts.py +27 -0
  11. sru_generator-1.0.0/sru_generator/builders.py +79 -0
  12. sru_generator-1.0.0/sru_generator/character_converters.py +383 -0
  13. sru_generator-1.0.0/sru_generator/cli.py +279 -0
  14. sru_generator-1.0.0/sru_generator/config.py +365 -0
  15. sru_generator-1.0.0/sru_generator/currency.py +188 -0
  16. sru_generator-1.0.0/sru_generator/exceptions.py +90 -0
  17. sru_generator-1.0.0/sru_generator/models.py +61 -0
  18. sru_generator-1.0.0/sru_generator/py.typed +0 -0
  19. sru_generator-1.0.0/sru_generator/sru_generator.py +839 -0
  20. sru_generator-1.0.0/sru_generator/utils.py +44 -0
  21. sru_generator-1.0.0/sru_generator/validators.py +586 -0
  22. sru_generator-1.0.0/sru_generator.egg-info/PKG-INFO +404 -0
  23. sru_generator-1.0.0/sru_generator.egg-info/SOURCES.txt +39 -0
  24. sru_generator-1.0.0/sru_generator.egg-info/dependency_links.txt +1 -0
  25. sru_generator-1.0.0/sru_generator.egg-info/entry_points.txt +2 -0
  26. sru_generator-1.0.0/sru_generator.egg-info/top_level.txt +1 -0
  27. sru_generator-1.0.0/tests/__init__.py +1 -0
  28. sru_generator-1.0.0/tests/golden/blanketter_mixed.sru +97 -0
  29. sru_generator-1.0.0/tests/golden/blanketter_stock_only.sru +68 -0
  30. sru_generator-1.0.0/tests/test_cli.py +522 -0
  31. sru_generator-1.0.0/tests/test_converter_loading.py +178 -0
  32. sru_generator-1.0.0/tests/test_currency.py +99 -0
  33. sru_generator-1.0.0/tests/test_encoding_and_quantity.py +200 -0
  34. sru_generator-1.0.0/tests/test_enhanced_features.py +308 -0
  35. sru_generator-1.0.0/tests/test_examples.py +51 -0
  36. sru_generator-1.0.0/tests/test_greek_transliteration.py +55 -0
  37. sru_generator-1.0.0/tests/test_lower_level.py +146 -0
  38. sru_generator-1.0.0/tests/test_properties.py +172 -0
  39. sru_generator-1.0.0/tests/test_runtime_fixes.py +320 -0
  40. sru_generator-1.0.0/tests/test_sru_generator.py +600 -0
  41. sru_generator-1.0.0/tests/test_validators_and_config.py +140 -0
@@ -0,0 +1,64 @@
1
+ # Changelog
2
+
3
+ All notable changes to this project are documented in this file. The format follows
4
+ [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and the project uses
5
+ [semantic versioning](https://semver.org/).
6
+
7
+ ## [1.0.0] - 2026-11-22
8
+
9
+ First public release.
10
+
11
+ ### What it does
12
+ - Builds the SRU files Skatteverket's e-service imports for **bilaga K4**: `INFO.SRU`
13
+ (`build_info_sru`) and `BLANKETTER.SRU` (`build_blanketter_sru`), with section A rows
14
+ in pages of nine, page numbers (7014) and page totals (3300/3301/3304/3305).
15
+ - Merges K4 **section D** pages (e.g. crypto) from an existing SRU file
16
+ (`read_crypto_sru_content`), in UTF-8 or ISO-8859-1 and with 7014 anywhere on a page;
17
+ a crypto-only year is supported.
18
+ - A command-line tool, `sru-generator info` / `sru-generator trades`, which takes
19
+ personal details from options, environment variables (`SRU_PERSONAL_NUMBER`, ...) or a
20
+ JSON profile, so the personnummer need not enter shell history.
21
+
22
+ ### Skatteverket's rules
23
+ - **Rounding per column:** försäljningspris rounds öre down, omkostnadsbelopp rounds öre
24
+ up, and vinst/förlust is derived from the two rounded amounts; page totals are the sums
25
+ of the rows printed above them.
26
+ - **ISO-8859-1** output; characters the encoding cannot hold are refused with a
27
+ `DataFormatError` that names them, never written as `?`.
28
+ - **Personnummer:** 12 digits with century and a correct check digit.
29
+ - Text values may not contain `#` or line breaks; `year` must be a four-digit income year;
30
+ at most nine rows per page; merged crypto lines must be section D fields, numbered 1..n.
31
+
32
+ ### Correctness and safety
33
+ - All arithmetic in `Decimal`. A `float` is read at 15 significant digits, so binary noise
34
+ (`0.1 * 3 * 1000 == 300.00000000000006`) cannot move a krona; exact input is used as
35
+ given. The CLI reads JSON numbers as `Decimal`.
36
+ - Fractional quantities are accepted and rounded up to a whole antal.
37
+ - Validation errors are `ValidationError` / `DataFormatError` / `ConfigurationError`
38
+ (all `SRUGeneratorError`), never raw `decimal` or `TypeError` exceptions.
39
+ - SRU files are written readable by their owner only (`0600`); importing the package
40
+ configures no logging; no network access, no runtime dependencies.
41
+ - Character conversion for names ISO-8859-1 cannot hold comes from the optional
42
+ [text-converters](https://github.com/Nikolaos-Paximadakis/text-converters) package:
43
+ `load_character_converter(name)` (also behind the CLI's `--character-conversion` and
44
+ `SRUConfig.get_character_converter()`) imports it lazily when installed (tested with
45
+ 0.2.0: `pip install "git+https://github.com/Nikolaos-Paximadakis/text-converters.git@v0.2.0"`);
46
+ `"none"` imports nothing. sru-generator still has no runtime dependencies. The bundled
47
+ fallback gives the same output as text-converters 0.2.0, including French œ/æ as oe/ae.
48
+
49
+ ### Quality
50
+ - Typed (`py.typed`); `mypy --strict` and pyright strict pass. ruff, strict pytest
51
+ (warnings are errors), 99% test coverage including property-based tests of the K4
52
+ rules, and tests that run every example.
53
+ - Python 3.11-3.14.
54
+
55
+ ### Deprecated
56
+ - The character converters bundled with sru-generator: used as a fallback, with a
57
+ `DeprecationWarning` (and a note on the CLI's stderr), when text-converters is not
58
+ installed or is outdated. They will be removed in 2.0, as will the top-level names
59
+ `convert_*_characters_to_english`, `get_character_converter`, `CHARACTER_CONVERTERS`
60
+ and `no_conversion` (they warn when used; use `load_character_converter` or
61
+ `text_converters`).
62
+ - `SRUConfig` fields that nothing reads (`validation_level`, `rounding_mode`,
63
+ `auto_convert_currency`, `log_level`, `custom_validators`, ...) warn when set and will
64
+ be removed in 2.0.
@@ -0,0 +1,62 @@
1
+ # Disclaimer
2
+
3
+ **sru-generator is not tax advice, and it is not affiliated with, endorsed by or
4
+ supported by Skatteverket (the Swedish Tax Agency).**
5
+
6
+ ## What it does, and what it leaves to you
7
+
8
+ sru-generator turns figures you supply into the SRU files that Skatteverket's
9
+ e-service imports for bilaga K4. It applies the file format and the rounding rules
10
+ described in Skatteverket's published help text, as the authors understood them at
11
+ the time of each release. Skatteverket can change those rules and the file format at
12
+ any time.
13
+
14
+ It does **not** decide anything about your taxes. In particular, it does not fetch
15
+ your trades, convert foreign currency, choose a cost-basis method (genomsnittsmetoden
16
+ or schablonmetoden), decide which K4 section an asset belongs in, or check that your
17
+ input is complete or correct. Those are your inputs and your decisions.
18
+
19
+ ## Your responsibility
20
+
21
+ The person who submits a tax declaration is responsible for its content, whichever
22
+ tool produced the file. Skatteverket can charge a tax surcharge (skattetillägg) for
23
+ incorrect information. Before you sign:
24
+
25
+ - check every row and total of the imported K4 in Skatteverket's e-service;
26
+ - keep the records the figures came from (broker statements, purchase history);
27
+ - ask a qualified tax adviser, or Skatteverket, if you are unsure how something
28
+ should be reported.
29
+
30
+ ## No warranty, no liability
31
+
32
+ The software is provided "as is", without warranty of any kind, under the
33
+ [MIT License](https://github.com/Nikolaos-Paximadakis/sru-generator/blob/main/LICENSE).
34
+ To the fullest extent permitted by law, the authors and contributors are not liable
35
+ for errors in any tax declaration, for tax surcharges, interest or penalties, or for
36
+ any other loss or damage arising from the use of this software.
37
+
38
+ ---
39
+
40
+ ## Ansvarsfriskrivning (svenska)
41
+
42
+ **sru-generator är inte skatterådgivning och har ingen koppling till Skatteverket.
43
+ Programmet är varken godkänt eller stöttat av Skatteverket.**
44
+
45
+ Programmet omvandlar uppgifter som du själv lämnar till SRU-filer för bilaga K4. Det
46
+ tillämpar filformatet och avrundningsreglerna i Skatteverkets publicerade
47
+ hjälptexter, så som upphovspersonerna har tolkat dem vid varje version. Reglerna och
48
+ filformatet kan ändras.
49
+
50
+ Programmet fattar inga beslut om din beskattning. Det hämtar inte dina affärer,
51
+ räknar inte om utländsk valuta, väljer inte metod för omkostnadsbeloppet och
52
+ kontrollerar inte att dina uppgifter är fullständiga eller riktiga.
53
+
54
+ Den som lämnar deklarationen ansvarar för innehållet, oavsett vilket verktyg som har
55
+ skapat filen. Skatteverket kan ta ut skattetillägg för oriktiga uppgifter. Granska
56
+ varje rad och summa i Skatteverkets e-tjänst innan du skriver under, och spara
57
+ underlagen.
58
+
59
+ Programmet tillhandahålls i befintligt skick ("as is"), utan garantier av något slag,
60
+ enligt MIT-licensen. Upphovspersonerna och bidragsgivarna ansvarar, i den utsträckning
61
+ lagen tillåter, inte för fel i deklarationer, skattetillägg, ränta eller annan skada
62
+ som uppstår genom användning av programmet.
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2024-2026 Nikos Paximadakis
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
@@ -0,0 +1,3 @@
1
+ include CHANGELOG.md DISCLAIMER.md
2
+ recursive-include tests *.py *.sru
3
+ global-exclude __pycache__ *.py[cod]
@@ -0,0 +1,404 @@
1
+ Metadata-Version: 2.4
2
+ Name: sru-generator
3
+ Version: 1.0.0
4
+ Summary: Generate Swedish Skatteverket SRU files (INFO.SRU + BLANKETTER.SRU) for the K4 capital-gains form.
5
+ Author-email: Nikos Paximadakis <nikos.paximadakis@gmail.com>
6
+ License-Expression: MIT
7
+ Project-URL: Homepage, https://github.com/Nikolaos-Paximadakis/sru-generator
8
+ Project-URL: Repository, https://github.com/Nikolaos-Paximadakis/sru-generator
9
+ Project-URL: Issues, https://github.com/Nikolaos-Paximadakis/sru-generator/issues
10
+ Project-URL: Changelog, https://github.com/Nikolaos-Paximadakis/sru-generator/blob/main/CHANGELOG.md
11
+ Keywords: sru,skatteverket,k4,deklaration,tax,sweden,swedish-tax,capital-gains,crypto
12
+ Classifier: Development Status :: 4 - Beta
13
+ Classifier: Environment :: Console
14
+ Classifier: Intended Audience :: Developers
15
+ Classifier: Intended Audience :: Financial and Insurance Industry
16
+ Classifier: Natural Language :: Swedish
17
+ Classifier: Operating System :: OS Independent
18
+ Classifier: Programming Language :: Python :: 3
19
+ Classifier: Programming Language :: Python :: 3 :: Only
20
+ Classifier: Programming Language :: Python :: 3.11
21
+ Classifier: Programming Language :: Python :: 3.12
22
+ Classifier: Programming Language :: Python :: 3.13
23
+ Classifier: Programming Language :: Python :: 3.14
24
+ Classifier: Topic :: Office/Business :: Financial
25
+ Classifier: Topic :: Office/Business :: Financial :: Accounting
26
+ Classifier: Typing :: Typed
27
+ Requires-Python: >=3.11
28
+ Description-Content-Type: text/markdown
29
+ License-File: LICENSE
30
+ Dynamic: license-file
31
+
32
+ # sru-generator
33
+
34
+ [![CI](https://github.com/Nikolaos-Paximadakis/sru-generator/actions/workflows/ci.yml/badge.svg)](https://github.com/Nikolaos-Paximadakis/sru-generator/actions/workflows/ci.yml)
35
+ [![Python 3.11+](https://img.shields.io/badge/python-3.11+-blue.svg)](https://www.python.org/downloads/)
36
+ [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://github.com/Nikolaos-Paximadakis/sru-generator/blob/main/LICENSE)
37
+ [![Not tax advice](https://img.shields.io/badge/Not-tax%20advice-orange.svg)](https://github.com/Nikolaos-Paximadakis/sru-generator/blob/main/DISCLAIMER.md)
38
+
39
+ Generate the SRU files (`INFO.SRU` + `BLANKETTER.SRU`) that Skatteverket's e-service
40
+ imports for **bilaga K4**: sales of shares, funds and crypto. Pure Python, no
41
+ dependencies.
42
+
43
+ > **Not tax advice. Not affiliated with Skatteverket.** You are responsible for every figure
44
+ > you submit: check the imported K4 in Skatteverket's e-service before you sign. Provided
45
+ > as is, without warranty — see the [disclaimer](https://github.com/Nikolaos-Paximadakis/sru-generator/blob/main/DISCLAIMER.md) (also in
46
+ > Swedish) and the [license](https://github.com/Nikolaos-Paximadakis/sru-generator/blob/main/LICENSE).
47
+
48
+ **Who it is for:** people writing a tool that turns broker or exchange exports into a
49
+ K4. Most such tools are tied to one broker and re-implement the same file details. This
50
+ package is that shared part: page grouping, field codes, Skatteverket's rounding rules,
51
+ page totals and the file encoding. You bring the figures, already in SEK; it writes the
52
+ file.
53
+
54
+ **På svenska:** ett Python-bibliotek som skapar SRU-filer för bilaga K4 (försäljning av
55
+ aktier, fonder och kryptovalutor) som kan importeras i Skatteverkets e-tjänst. Du lämnar
56
+ beloppen i kronor; biblioteket sköter filformatet, avrundningen och summeringen. Inte
57
+ skatterådgivning — du ansvarar själv för deklarationen.
58
+
59
+ ## Install
60
+
61
+ ```bash
62
+ pip install sru-generator
63
+ ```
64
+
65
+ Python 3.11 or newer.
66
+
67
+ ## Quick start
68
+
69
+ ```python
70
+ from sru_generator import build_blanketter_sru, build_info_sru, write_sru_file
71
+
72
+ me = {
73
+ "personal_number": "198112189876", # made-up example
74
+ "full_name": "Test Person",
75
+ "postal_code": "11122",
76
+ "city_name": "Stockholm",
77
+ }
78
+ sales = [
79
+ {
80
+ "quantity": 100,
81
+ "stock": "Ericsson B",
82
+ "net value": 15000.75, # försäljningspris, SEK
83
+ "total net value of purchase": 14000.20, # omkostnadsbelopp, SEK
84
+ },
85
+ {
86
+ "quantity": 2.5, # fractional shares are fine; written rounded up
87
+ "stock": "Investor B",
88
+ "net value": 2000,
89
+ "total net value of purchase": 2600,
90
+ },
91
+ ]
92
+
93
+ write_sru_file("INFO.SRU", build_info_sru(me))
94
+ write_sru_file("BLANKETTER.SRU", build_blanketter_sru(sales, me, year=2025))
95
+ ```
96
+
97
+ `BLANKETTER.SRU` then contains (the header's date and time will differ):
98
+
99
+ ```text
100
+ #BLANKETT K4-2025P4
101
+ #IDENTITET 198112189876 20260301 120000
102
+ #NAMN Test Person
103
+ #UPPGIFT 7014 1
104
+ #UPPGIFT 3100 100
105
+ #UPPGIFT 3101 Ericsson B
106
+ #UPPGIFT 3102 15000
107
+ #UPPGIFT 3103 14001
108
+ #UPPGIFT 3104 999
109
+ #UPPGIFT 3110 3
110
+ #UPPGIFT 3111 Investor B
111
+ #UPPGIFT 3112 2000
112
+ #UPPGIFT 3113 2600
113
+ #UPPGIFT 3115 600
114
+ #UPPGIFT 3300 17000
115
+ #UPPGIFT 3301 16601
116
+ #UPPGIFT 3304 999
117
+ #UPPGIFT 3305 600
118
+ #BLANKETTSLUT
119
+ #FIL_SLUT
120
+ ```
121
+
122
+ Note the rounding: 15000.75 became 15000 and 14000.20 became 14001 (see
123
+ [Rounding](#rounding)). Up to nine sales go on each K4 page; more sales give more pages.
124
+
125
+ Then, in Skatteverket's **Inkomstdeklaration 1** e-service, open **Bilagor**, choose K4,
126
+ then **Importera** and select `BLANKETTER.SRU` (see Skatteverket's page
127
+ [Lämna en bilaga till deklarationen](https://skatteverket.se/privat/deklaration/lamnaenbilagatilldeklarationen.4.515a6be615c637b9aa46366.html)).
128
+ `INFO.SRU` is needed when you send files through Skatteverket's Filöverföring service.
129
+ **Check every row and total in the e-service before you sign.**
130
+
131
+ ### Command line
132
+
133
+ The same from a shell. Personal details can come from options, environment variables or
134
+ a JSON profile; prefer the environment or a profile for the personnummer, because
135
+ command-line arguments end up in shell history.
136
+
137
+ ```bash
138
+ export SRU_PERSONAL_NUMBER=198112189876 SRU_FULL_NAME="Test Person"
139
+ sru-generator info --postal-code 11122 --city-name Stockholm # writes INFO.SRU
140
+ sru-generator trades --data sales.json --year 2025 # writes BLANKETTER.SRU
141
+
142
+ # or keep everything in a profile file (git-ignored if named profile*.json):
143
+ sru-generator info --profile profile.json
144
+ ```
145
+
146
+ `sales.json` is a JSON list of the same dictionaries as `sales` above. `--year` defaults
147
+ to last year. Run `sru-generator trades --help` for the other options (crypto file,
148
+ character conversion, output path, `-v` for log messages).
149
+
150
+ ## What the package does — and does not do
151
+
152
+ It **does**:
153
+
154
+ - validate each sale and your personal details, with clear errors;
155
+ - round each amount the way Skatteverket's K4 help text says (below);
156
+ - derive vinst/förlust from the rounded amounts, so every row adds up;
157
+ - split sales into pages of nine, number them, and write each page's totals;
158
+ - write ISO-8859-1, refusing characters that encoding cannot hold instead of writing `?`;
159
+ - merge K4 section D pages from an existing crypto SRU file with the share pages.
160
+
161
+ It does **not**:
162
+
163
+ - read broker or exchange exports;
164
+ - convert foreign currency for you (helpers exist, but nothing converts automatically);
165
+ - choose a cost-basis method (genomsnittsmetoden or schablonmetoden) or decide which K4
166
+ section an asset belongs in;
167
+ - generate section D rows itself (it merges them from an existing file). Crypto belongs
168
+ in section D, not in the share rows this package writes;
169
+ - contact Skatteverket or anything else on the network.
170
+
171
+ ## Rounding
172
+
173
+ K4 amounts are whole kronor, and Skatteverket gives a different rule per column
174
+ ([help text for bilaga K4](https://www8.skatteverket.se/hjalptexter/EfInk1k4_aktie.html)):
175
+
176
+ - **Försäljningspris:** öre rounded **down**.
177
+ - **Omkostnadsbelopp:** öre rounded **up**.
178
+ - **Vinst/förlust:** försäljningspris minus omkostnadsbelopp, *after* rounding. It is
179
+ never rounded on its own. A `profit/loss` you supply is only cross-checked against
180
+ the unrounded difference (tolerance 1 kr) and a warning is logged if it differs; it
181
+ is not written.
182
+
183
+ A `float` is first read at 15 significant digits, so its binary noise cannot move a
184
+ figure by a krona: `0.1 * 3 * 1000` is `300.00000000000006`, which would otherwise
185
+ round *up* to an omkostnadsbelopp of 301. `Decimal`, `int` and `str` are exact and are
186
+ used as given, so `Decimal("100.001")` still rounds up to 101. (A float with more than
187
+ 15 significant digits, such as `1.999999999999999`, cannot be told apart from noise and
188
+ is read as 2.) Prefer `Decimal` or strings for money; the CLI reads JSON numbers as
189
+ `Decimal`.
190
+
191
+ Page totals (3300, 3301, 3304, 3305) are the sums of the rows printed above them. Many
192
+ other K4 tools round every amount to the nearest krona, so their figures can differ from
193
+ this package's by 1 kr per row.
194
+
195
+ `quantity` (antal) may be fractional and is rounded **up** to a whole number, so a sale
196
+ of 0.25 units shows 1, not 0: section A's antal is a whole number in Skatteverket's file
197
+ description. Antal does not affect the gain or loss.
198
+
199
+ `year` must be a four-digit income year from 2000: `K4-2025P4` declares income year
200
+ 2025. `items_per_group` (rows per page) may be 1–9, the rows K4 section A has.
201
+
202
+ ## Input reference
203
+
204
+ ### A sale
205
+
206
+ | Key | Type | Required | Meaning | Allowed |
207
+ |-----|------|----------|---------|---------|
208
+ | `quantity` | number | yes | Units sold; fractions allowed, written rounded up | 0 – 999,999,999,999 |
209
+ | `stock` | string | yes | Name of the security (Beteckning) | 1–80 characters, no `#` or line breaks |
210
+ | `net value` | number | yes | Försäljningspris in SEK, after fees | 0 – 999,999,999,999 |
211
+ | `total net value of purchase` | number | yes | Omkostnadsbelopp in SEK, including fees | 0 – 999,999,999,999 |
212
+ | `profit/loss` | number | no | Your own figure, cross-checked only | |
213
+ | `currency` | string | no | Validated only (see below); amounts must already be SEK | one of the supported codes |
214
+ | `exchange_rate` | number | no | Validated only | 0.000001 – 1,000,000 |
215
+
216
+ Numbers may be `int`, `float`, `Decimal` or numeric strings; all arithmetic uses
217
+ `Decimal`.
218
+
219
+ ### Personal details
220
+
221
+ | Key | Meaning | Allowed |
222
+ |-----|---------|---------|
223
+ | `personal_number` | Personnummer with century, as Skatteverket requires: `198112189876` (a hyphen before the last four digits is accepted) | 12 digits, correct check digit |
224
+ | `full_name` | Name | 1–100 characters, no `#` or line breaks |
225
+ | `postal_code` | Postnummer | 5 digits |
226
+ | `city_name` | Postort | 1–50 characters, no `#` or line breaks |
227
+
228
+ ### Characters
229
+
230
+ SRU files are ISO-8859-1, so Swedish letters (å, ä, ö, é) are written as they are and
231
+ need no conversion. Text the encoding cannot hold — Greek, Cyrillic, `€`, typographic
232
+ quotes — makes `write_sru_file` (returns `False`) and `encode_sru_content` (raises
233
+ `DataFormatError`) fail with a message naming the characters, instead of silently
234
+ writing `?`. Pass a `character_converter` (any `str -> str` function) to transliterate
235
+ stock names.
236
+
237
+ **Converters come from [text-converters](https://github.com/Nikolaos-Paximadakis/text-converters).**
238
+ Install it to use the named converters (`greek`, `swedish`, `german`, `french`,
239
+ `spanish`):
240
+
241
+ ```bash
242
+ pip install "git+https://github.com/Nikolaos-Paximadakis/text-converters.git@v0.2.0"
243
+ ```
244
+
245
+ ```python
246
+ from sru_generator import build_blanketter_sru, load_character_converter
247
+
248
+ greek = load_character_converter("greek") # from text-converters when installed
249
+ content = build_blanketter_sru(sales, me, year=2025, character_converter=greek)
250
+ ```
251
+
252
+ sru-generator still has no dependencies: text-converters is optional and imported only
253
+ when a named converter is asked for (`"none"` never imports it). Without it,
254
+ `load_character_converter` falls back to a copy bundled with sru-generator and warns
255
+ (`DeprecationWarning`) that the copy will be removed in 2.0; the CLI's
256
+ `--character-conversion` prints the same note on stderr. An outdated text-converters
257
+ (one whose Greek converter does not give `Thessaloniki` for `Θεσσαλονίκη`) is not used.
258
+
259
+ `greek` follows the Greek standard ELOT 743 letter by letter (η is `i`, ου is `ou`,
260
+ Θ/Χ/Ψ give `Th`/`Ch`/`Ps`, or `TH`/`CH`/`PS` in a word written in capitals) but not its
261
+ other letter pairs: `Ευαγγελισμός` becomes `Eyaggelismos`, not `Evangelismos`. `french`
262
+ writes œ/æ as `oe`/`ae`. The `swedish` converter strips å, ä and ö, which SRU files
263
+ do not require.
264
+
265
+ **For names in other scripts:** convert only the characters ISO-8859-1 cannot hold.
266
+ Apply the Greek converter first, then a transliteration library such as
267
+ [anyascii](https://pypi.org/project/anyascii/) (ISC licence) for any other script:
268
+
269
+ ```python
270
+ from anyascii import anyascii
271
+ from text_converters import convert_greek_characters_to_english
272
+
273
+ from sru_generator import build_blanketter_sru
274
+
275
+
276
+ def to_latin1(text: str) -> str:
277
+ """Transliterate only what ISO-8859-1 cannot hold; keep å, ä, ö as they are."""
278
+ text = convert_greek_characters_to_english(text)
279
+ return "".join(c if ord(c) <= 0xFF else anyascii(c) for c in text)
280
+
281
+
282
+ content = build_blanketter_sru(sales, me, year=2025, character_converter=to_latin1)
283
+ ```
284
+
285
+ | Input | `to_latin1` | `anyascii` alone | `greek` |
286
+ |---|---|---|---|
287
+ | `Åsa Öberg` | `Åsa Öberg` | `Asa Oberg` | `Åsa Öberg` |
288
+ | `Θεσσαλονίκη Χανιά` | `Thessaloniki Chania` | `Thessaloniki Chania` | `Thessaloniki Chania` |
289
+ | `Παπαδόπουλος` | `Papadopoulos` | `Papadopoylos` | `Papadopoulos` |
290
+ | `Москва` | `Moskva` | `Moskva` | `Москва` (still fails) |
291
+ | `Ørsted €` | `Ørsted EUR` | `Orsted EUR` | `Ørsted €` (still fails) |
292
+
293
+ Don't pass `anyascii` directly: it converts *every* non-ASCII character, so Swedish
294
+ names would lose their å, ä and ö for no reason.
295
+
296
+ ## More features
297
+
298
+ ### Crypto pages (K4 section D)
299
+
300
+ If another tool produced a K4 SRU file with section D rows (for example from a crypto
301
+ tax service), merge its pages with your share pages:
302
+
303
+ ```python
304
+ from sru_generator import build_blanketter_sru, read_crypto_sru_content
305
+
306
+ crypto_pages = read_crypto_sru_content("crypto_k4.sru") # UTF-8 or ISO-8859-1
307
+ content = build_blanketter_sru(sales, me, year=2025, crypto_groups=crypto_pages)
308
+ ```
309
+
310
+ With only crypto pages and no share sales, pass `sales=[]`.
311
+
312
+ The pages are checked before they are merged: every line must be a section D field
313
+ (`#UPPGIFT 3410`–`3475`, or the totals `3500`, `3501`, `3503`, `3504`), and the pages
314
+ must be numbered 1..n. `7014` (the page number) may appear anywhere on a page; a page
315
+ without it is numbered by its position. A file that cannot be read raises
316
+ `FileOperationError`, an unreadable page number `DataFormatError`; a missing file gives
317
+ an empty list and a warning.
318
+
319
+ ### Currency helpers
320
+
321
+ Nothing is converted automatically. If you want help converting before you build:
322
+
323
+ ```python
324
+ from sru_generator import convert_to_sek, set_exchange_rate
325
+
326
+ set_exchange_rate("USD", "SEK", 10.5)
327
+ sek = convert_to_sek(1500, "USD") # Decimal("15750.00")
328
+ ```
329
+
330
+ Supported codes: SEK, USD, EUR, GBP, NOK, DKK, CHF, JPY, CAD, AUD. Which rate to use
331
+ (the transaction day's or an average) is a tax question; check Skatteverket's guidance.
332
+
333
+ ### Validation on its own
334
+
335
+ ```python
336
+ from sru_generator import ValidationError, validate_personal_info, validate_trade_data
337
+
338
+ try:
339
+ rows = validate_trade_data(sales)
340
+ person = validate_personal_info(me)
341
+ except ValidationError as e:
342
+ print(f"{e.field}: {e}")
343
+ ```
344
+
345
+ `build_info_sru` and `build_blanketter_sru` run these for you.
346
+
347
+ ### Configuration
348
+
349
+ `SRUConfig` / `create_config(...)` bundle the character converter, default currency and
350
+ exchange rates for applications that want one object to pass around. The K4 rounding
351
+ rule is not configurable. Several older fields (`validation_level`, `rounding_mode`,
352
+ `auto_convert_currency`, `log_level`, `custom_validators`, …) are read by nothing;
353
+ setting one raises a `DeprecationWarning`, and they will be removed in 2.0.
354
+
355
+ ### Logging
356
+
357
+ The package logs through the standard `logging` module under the name `sru_generator`
358
+ and is silent unless your application configures logging, for example
359
+ `logging.basicConfig(level=logging.INFO)`. Messages can include stock names and
360
+ amounts. The CLI shows warnings by default and more with `-v`.
361
+
362
+ ## API overview
363
+
364
+ - **Build whole files:** `build_info_sru`, `build_blanketter_sru`, `write_sru_file`,
365
+ `encode_sru_content` (bytes, for downloads or HTTP responses)
366
+ - **Lower level:** `generate_sru_info_content`, `generate_sru_trade_content` (pages
367
+ only, without the closing `#FIL_SLUT`), `merge_sru_groups`, `read_crypto_sru_content`,
368
+ `round_k4_sale_price`, `round_k4_cost_basis`, `round_k4_quantity`
369
+ - **Validation:** `validate_trade_data`, `validate_personal_info`,
370
+ `TradeDataValidator`, `PersonalInfoValidator`, `create_custom_validator`
371
+ - **Characters and encoding:** `load_character_converter` (text-converters, or the
372
+ bundled copy until 2.0), `encode_sru_text`, `decode_sru_bytes`, `SRU_ENCODING`.
373
+ `get_character_converter`, `CHARACTER_CONVERTERS`, `no_conversion` and the
374
+ `convert_*_characters_to_english` functions at the top level are deprecated.
375
+ - **Currency:** `convert_to_sek`, `convert_currency`, `set_exchange_rate`,
376
+ `CurrencyConverter`
377
+ - **Configuration:** `SRUConfig`, `create_config`, `get_default_config`
378
+ - **Exceptions** (all subclass `SRUGeneratorError`): `ValidationError`,
379
+ `BusinessRuleError`, `DataFormatError`, `CurrencyError`, `ConfigurationError`,
380
+ `FileOperationError`
381
+
382
+ ## Privacy and security
383
+
384
+ SRU files hold your personnummer and your transactions. The package writes them readable
385
+ by you only, never touches the network, and logs nothing unless asked. Never paste a real
386
+ SRU file or personnummer into an issue. See
387
+ [SECURITY.md](https://github.com/Nikolaos-Paximadakis/sru-generator/blob/main/SECURITY.md).
388
+
389
+ ## Related projects
390
+
391
+ Broker-specific K4 tools that could build on a library like this include
392
+ [K4SRU](https://github.com/ebtcap/K4SRU) (Java, several brokers),
393
+ [IbkrToSru](https://github.com/JohanLarsson/IbkrToSru) (C#, IBKR) and
394
+ [K4Skatt](https://github.com/duga3/K4Skatt) (Python, IBKR).
395
+ [pysru-mab](https://pypi.org/project/pysru-mab/) reads and writes general SRU files and
396
+ targets the company forms (INK2).
397
+
398
+ ## Contributing, changelog, license
399
+
400
+ - [CONTRIBUTING.md](https://github.com/Nikolaos-Paximadakis/sru-generator/blob/main/CONTRIBUTING.md)
401
+ — setup, checks, and what belongs in this package
402
+ - [CHANGELOG.md](https://github.com/Nikolaos-Paximadakis/sru-generator/blob/main/CHANGELOG.md)
403
+ - [MIT License](https://github.com/Nikolaos-Paximadakis/sru-generator/blob/main/LICENSE)
404
+ and [disclaimer](https://github.com/Nikolaos-Paximadakis/sru-generator/blob/main/DISCLAIMER.md)