pyskins 0.1.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 (39) hide show
  1. pyskins-0.1.0/.apm/instructions/pyskins.instructions.md +14 -0
  2. pyskins-0.1.0/.apm/skills/pyskins/SKILL.md +162 -0
  3. pyskins-0.1.0/.gitignore +46 -0
  4. pyskins-0.1.0/CONTRIBUTING.md +92 -0
  5. pyskins-0.1.0/LICENSE +21 -0
  6. pyskins-0.1.0/PKG-INFO +391 -0
  7. pyskins-0.1.0/README.md +368 -0
  8. pyskins-0.1.0/assets/build_cards.py +114 -0
  9. pyskins-0.1.0/assets/button-ai.svg +4 -0
  10. pyskins-0.1.0/assets/button-demo.svg +4 -0
  11. pyskins-0.1.0/assets/button-examples.svg +4 -0
  12. pyskins-0.1.0/assets/button-hide.svg +4 -0
  13. pyskins-0.1.0/assets/button-install.svg +4 -0
  14. pyskins-0.1.0/assets/card-christmas.svg +45 -0
  15. pyskins-0.1.0/assets/card-faces.svg +19 -0
  16. pyskins-0.1.0/assets/card-python.svg +18 -0
  17. pyskins-0.1.0/examples/christmas_countdown.py +28 -0
  18. pyskins-0.1.0/examples/fizzbuzz.py +17 -0
  19. pyskins-0.1.0/examples/guess_the_number.py +26 -0
  20. pyskins-0.1.0/examples/pet_names.py +23 -0
  21. pyskins-0.1.0/examples/robot.py +29 -0
  22. pyskins-0.1.0/examples/rocket_launch.py +37 -0
  23. pyskins-0.1.0/examples/secret_santa.py +23 -0
  24. pyskins-0.1.0/examples/skins/easter.json +14 -0
  25. pyskins-0.1.0/examples/skins/php.json +19 -0
  26. pyskins-0.1.0/pyproject.toml +44 -0
  27. pyskins-0.1.0/pyskins/__init__.py +11 -0
  28. pyskins-0.1.0/pyskins/__main__.py +5 -0
  29. pyskins-0.1.0/pyskins/cli.py +580 -0
  30. pyskins-0.1.0/pyskins/codec.py +57 -0
  31. pyskins-0.1.0/pyskins/engine.py +242 -0
  32. pyskins-0.1.0/pyskins/obfuscate.py +93 -0
  33. pyskins-0.1.0/pyskins/sample.py +45 -0
  34. pyskins-0.1.0/pyskins/skins/christmas.json +68 -0
  35. pyskins-0.1.0/pyskins/skins/faces.json +68 -0
  36. pyskins-0.1.0/pyskins/skins.py +206 -0
  37. pyskins-0.1.0/pyskins.pth +1 -0
  38. pyskins-0.1.0/tests/stress.py +114 -0
  39. pyskins-0.1.0/tests/test_pyskins.py +834 -0
@@ -0,0 +1,14 @@
1
+ ---
2
+ description: How to handle Python files that wear an emoji skin, which start with a coding line that names a pyskins skin
3
+ applyTo: "**/*.py"
4
+ ---
5
+
6
+ # Python files that wear a skin
7
+
8
+ If a `.py` file starts with a line such as `# coding: pyskins-christmas`, its keywords and names such as `print` are shown as emoji. It is a normal Python program wearing a skin from the `pyskins` tool. Files without that line are not affected by anything below.
9
+
10
+ - Run it like any Python file: `python robot.py`. This needs `pip install pyskins`. If that is missing, `pyskins run robot.py` works.
11
+ - Do not edit the emoji by hand, and do not write a skinned file by hand. One wrong emoji makes a file that does not run.
12
+ - To change it: `pyskins undo robot.py -o robot_plain.py`, edit and test the plain file, then `pyskins apply christmas robot_plain.py -o robot.py`.
13
+ - Keep the first line where it is. It tells Python which skin the file wears.
14
+ - Lint, format and type-check the plain file, not the skinned one. The editor underlining the emoji is expected.
@@ -0,0 +1,162 @@
1
+ ---
2
+ name: pyskins
3
+ description: Write and run Python files that are written in emoji, using the pyskins command to put a skin on normal Python or take it off. Use when the user asks for a program in a skin such as faces or christmas, when a Python file starts with a coding line that names a pyskins skin or shows emoji where keywords should be (for example ๐Ÿง instead of class), or when they want a new skin made.
4
+ ---
5
+
6
+ # Python skins
7
+
8
+ A skinned Python file is a normal `.py` file in which the keywords, and everyday names such as `print` and `len`, are shown as emoji. `class Robot:` is `๐Ÿง Robot:` in the `faces` skin and `๐ŸŽ„ Robot:` in the `christmas` skin.
9
+
10
+ The file starts with a line that names its skin:
11
+
12
+ ```text
13
+ # coding: pyskins-christmas
14
+ ```
15
+
16
+ With `pyskins` installed, Python reads that line and runs the file like any other: `python robot.py`. It is only a skin. Underneath it is the same Python, and it behaves exactly the same.
17
+
18
+ The people who use this are coding with an AI assistant, which is you. Nobody types these emoji on a keyboard. The user says what they want, and you produce the skinned program with the tool.
19
+
20
+ ## The one rule
21
+
22
+ Write the program as normal Python, and let `pyskins` put the skin on.
23
+
24
+ Do not write or edit emoji code yourself, not even one line. A skin maps about 60 words to 60 emoji, and nobody, person or model, recalls all of them reliably. One wrong emoji gives a file that does not run. The tool does not make that mistake: before it returns a skinned file, it takes the skin off again and checks that the result equals the original.
25
+
26
+ ## When the user wants a program in a skin
27
+
28
+ 1. Write the program as normal Python, in a working file such as `robot_plain.py`. Run it and test it as you always would.
29
+ 2. Put the skin on. The result is the file the user asked for:
30
+
31
+ ```sh
32
+ pyskins apply christmas robot_plain.py -o robot.py
33
+ ```
34
+
35
+ 3. Run the skinned file, to show that it works:
36
+
37
+ ```sh
38
+ python robot.py
39
+ ```
40
+
41
+ If Python stops with an error that names `pyskins-christmas` (it says `unknown encoding` or `encoding problem`), then `pyskins` is not installed for that Python. Use `pyskins run robot.py`, which always works, and tell the user that `pip install pyskins` makes plain `python` work too.
42
+
43
+ 4. Show the user the skinned code and what it printed.
44
+ 5. Ask whether they want to keep the plain working file. Most users want only the skinned one, because the skin is the point. Deleting the plain file loses nothing: `pyskins undo robot.py` brings it back at any time.
45
+
46
+ ## When the user wants a change to a skinned program
47
+
48
+ Take the skin off, change the Python, put the skin back on:
49
+
50
+ ```sh
51
+ pyskins undo robot.py -o robot_plain.py
52
+ # edit and test robot_plain.py
53
+ pyskins apply christmas robot_plain.py -o robot.py
54
+ python robot.py
55
+ ```
56
+
57
+ `pyskins undo` reads the skin from the first line of the file. `pyskins apply` refuses a file that already wears a skin, so you cannot skin a file twice by accident.
58
+
59
+ ## Commands
60
+
61
+ ```sh
62
+ pyskins list # the skins that are installed
63
+ pyskins show faces # every word of a skin, its emoji, and why
64
+ pyskins apply SKIN app.py # skin on, in place (adds the first line that names the skin)
65
+ pyskins apply -s ./my.json app.py # SKIN may be a built-in name or a path to a .json skin
66
+ python app.py # run it
67
+ pyskins run app.py [arguments] # run it, when pyskins is not installed into that Python
68
+ pyskins undo app.py # skin off, in place
69
+ ```
70
+
71
+ `apply`, `undo` and `obfuscate` change the file in place by default; `-o FILE` writes a copy and keeps the original. For `apply` and `undo`, `-o -` prints to the screen (`obfuscate` cannot print, because it also writes a key). `SKIN` is a built-in name such as `faces` or `christmas`, **or a path to the user's own `.json` skin** โ€” users are never limited to the built-ins, and need no library update to use their own.
72
+
73
+ `SKIN` is a name such as `faces` or `christmas`. Without `-o`, `apply` and `undo` change the file in place; pass `-o -` to print the result instead, or use `-` as the file to read from a pipe. `python -m pyskins` works the same as `pyskins`.
74
+
75
+ If `pyskins` is not installed, say so and ask before you install it:
76
+
77
+ ```sh
78
+ pip install pyskins
79
+ ```
80
+
81
+ It has no dependencies and runs on any Python 3.
82
+
83
+ ## What to expect
84
+
85
+ - A skin swaps a word only where Python reads it as a name. Strings, comments and f-strings are left alone, so `"if"` in a string stays `"if"`.
86
+ - Spacing, line endings and blank lines stay exactly as they were. The skinned file has one line more than the plain one: the first line.
87
+ - The first line must stay the first line (or the second, after a `#!` line). Python only looks there.
88
+ - Skinned files can import each other, and can import normal Python files.
89
+ - The editor underlines the emoji, because it does not know about skins. That is expected. Tell the user if they ask.
90
+ - Linters, formatters, type checkers and most test runners need normal Python. Take the skin off for those.
91
+ - `apply` refuses a file that is not valid Python. Fix the syntax error in the plain file first.
92
+ - If Python or `pyskins` reports a mistake in a skinned file, it was probably edited by hand. Take the skin off and fix the Python. Do not repair the emoji yourself.
93
+
94
+ When you show skinned code in a chat, put it in a `text` code block, not a `python` one.
95
+
96
+ ## Hiding what the code does (obfuscation)
97
+
98
+ A theme skin keeps the code readable. To hide it, `pyskins obfuscate` turns *everything* โ€” every name the user invented, every keyword, every string โ€” into emoji, while keeping the Python shape (indentation, punctuation, line breaks). It still runs, because the file carries a first line that names its key and pyskins turns it back before Python runs it.
99
+
100
+ ```sh
101
+ pyskins obfuscate app.py --skin christmas
102
+ ```
103
+
104
+ This changes `app.py` in place and writes `app.json` (the key) beside it; add `-o secret.py` to keep the original instead. The key is the only way back and the only way to run it, so tell the user to keep it.
105
+
106
+ - Run it: after `pyskins add app.json`, plain `python app.py` works; or `pyskins run --skin app.json app.py` without installing.
107
+ - Undo it: `pyskins undo app.py --skin app.json` gives the exact original.
108
+ - `-s/--skin SKIN` is optional: it flavours the keywords with a theme (christmas, faces). Without it they take plain emoji. Everything is hidden either way โ€” names like `greet` and keyword arguments like `tired=` included.
109
+
110
+ To obfuscate a whole project, give `obfuscate` a folder and a `-o` output folder. It hides every `.py` file through all subfolders with one shared key, copies other files so the tree still runs, and leaves the originals untouched:
111
+
112
+ ```sh
113
+ pyskins obfuscate myapp/ -o myapp_secret/ # whole tree, one key: myapp_secret.json
114
+ pyskins add myapp_secret.json # install the key once
115
+ python myapp_secret/app.py # runs like the original
116
+ pyskins undo myapp_secret/ -o myapp_back/ --skin myapp_secret.json # restore the whole tree
117
+ ```
118
+
119
+ Be honest with the user: this is not a secret keeper. The key `.json` is plaintext โ€” it lists the original names and strings next to their emoji โ€” so anyone with the key reads everything; tell the user to keep keys out of version control. Inside a `.py` everything is hidden โ€” names, keywords, strings, f-strings and comments all become emoji (a `#!` shebang on the first line is kept, since the OS reads it before Python). A string or f-string that spans several lines collapses to one emoji (`undo` restores it exactly); and obfuscating a folder copies non-`.py` files (a `.env`, a config) across unchanged. It hides code from a reader, not from anyone who has the key. Say so if the user expects real protection.
120
+
121
+ ## Making a new skin
122
+
123
+ Let the tool do the set-up and the checking:
124
+
125
+ ```sh
126
+ pyskins new pizza # writes pizza.json with every keyword and everyday name, empty
127
+ pyskins check pizza.json # reports broken rules and missing keywords, and tests the skin
128
+ pyskins add pizza.json # saves it to the user's own skins, so "pizza" works by name
129
+ ```
130
+
131
+ A skin is one JSON file. Each word gets a replacement and a few words that say why:
132
+
133
+ ```json
134
+ {
135
+ "name": "space",
136
+ "title": "Space",
137
+ "description": "Python among the stars.",
138
+ "words": {
139
+ "def": ["๐Ÿš€", "launch something"],
140
+ "return": ["๐Ÿ›ธ", "beam it back"],
141
+ "class": ["๐Ÿช", "a whole planet"]
142
+ }
143
+ }
144
+ ```
145
+
146
+ `pyskins check` validates the mapping:
147
+
148
+ - One replacement per word, and no replacement used twice.
149
+ - A replacement is emoji only, or one plain word made of letters. No spaces, and no signs such as `#`, `&` or `$`.
150
+ - No emoji may be part of another one in the same skin.
151
+
152
+ Three things a skin may do:
153
+
154
+ - Cover only some keywords. An empty entry means the word keeps its normal look.
155
+ - Use words in place of emoji, for example `"def": ["function", "PHP says function"]`. With a word skin, `apply` refuses a file that already uses one of those words as a name, and says which one.
156
+ - Build on another skin with `"extends": "faces"`, then list only the words that change.
157
+
158
+ Bundled skin names cannot be overridden. Choose a different name for a custom skin. `pyskins add` saves the resolved mapping, including inherited words.
159
+
160
+ It may also rename ordinary names such as `print` or `self`.
161
+
162
+ Choose replacements for meaning, so a reader can guess the word: a thinking face for `if`, a gift for `def` in a Christmas skin. Show the finished mapping to the user before you use it. Keep skins friendly: a child may read them.
@@ -0,0 +1,46 @@
1
+ __pycache__/
2
+ *.py[cod]
3
+ *.egg-info/
4
+ build/
5
+ dist/
6
+ .venv/
7
+ venv/
8
+ .cache/
9
+ .ruff_cache/
10
+ .pytest_cache/
11
+ .mypy_cache/
12
+ .coverage
13
+ .coverage.*
14
+ htmlcov/
15
+ .DS_Store
16
+ .idea/
17
+ .vscode/
18
+ *.log
19
+ *.swp
20
+ *.swo
21
+ *~
22
+ .env
23
+ .env.*
24
+ .envrc
25
+ .pypirc
26
+ .netrc
27
+ .aws/
28
+ .ssh/
29
+ *.pem
30
+ *.key
31
+ uv.lock
32
+
33
+ apm.lock.yaml
34
+ apm_modules/
35
+ .claude/
36
+ .agents/
37
+ .cursor/
38
+ AGENTS.md
39
+ CLAUDE.md
40
+
41
+ .python-version
42
+ .tool-versions
43
+ .pyskins-*
44
+ *.pyskin
45
+ *.bak
46
+ *.orig
@@ -0,0 +1,92 @@
1
+ # Add your own skin
2
+
3
+ You do not need to know how the engine works. A skin is one small text file, and the tool tells you when something is wrong. Ten minutes is enough.
4
+
5
+ ## The short way
6
+
7
+ ```sh
8
+ pyskins new pizza # 1. makes pizza.json with every word listed, empty
9
+ # 2. open pizza.json and fill in an emoji and a few words for each word
10
+ pyskins check pizza.json # 3. shows what is missing and tests the skin
11
+ pyskins undo examples/robot.py -o - | pyskins apply pizza.json - # 4. see it on real code
12
+ ```
13
+
14
+ When `check` is happy, move the file to `pyskins/skins/` and open a pull request. That is all.
15
+
16
+ A finished entry looks like this:
17
+
18
+ ```json
19
+ {
20
+ "name": "pizza",
21
+ "title": "Pizza",
22
+ "description": "Python with extra cheese.",
23
+ "words": {
24
+ "class": ["๐Ÿ•", "the whole pizza"],
25
+ "def": ["๐Ÿ”ช", "slice and prepare"],
26
+ "return": ["๐Ÿ›ต", "the delivery scooter"]
27
+ }
28
+ }
29
+ ```
30
+
31
+ ## What makes a good skin
32
+
33
+ - **A reader can guess the word.** A thinking face for `if`. A gift for `def` at Christmas. The few words after the emoji say why, and `pyskins show` prints them.
34
+ - **It has a theme.** Food, a holiday, a sport, a film style, your city.
35
+ - **It makes someone smile.** `raise` as a raised glass. `None` as an empty stocking.
36
+ - **It is kind.** A child may read this. Nothing rude, nothing scary.
37
+
38
+ ## The rules
39
+
40
+ The tool checks all of these for you. Each one exists so that a skin can always be taken off again.
41
+
42
+ 1. Each word gets one replacement, and no replacement is used twice.
43
+ 2. A replacement is either emoji only, or one plain word made of letters. No spaces, and no signs such as `#`, `&` or `$`.
44
+ 3. No emoji may be part of another emoji in the same skin.
45
+ 4. A skin made of emoji that lives in this repository covers all 35 keywords, and every word has its few words of "why". The 26 everyday names such as `print` and `len` are a bonus: cover as many as you have good ideas for.
46
+ 5. A skin made of words (like the PHP example) covers what makes sense.
47
+
48
+ ## Two more tricks
49
+
50
+ **Build on another skin.** Start from `faces` and change only a few words:
51
+
52
+ ```json
53
+ {
54
+ "name": "easter",
55
+ "extends": "faces",
56
+ "words": {
57
+ "class": ["๐Ÿงบ", "the basket that holds everything"],
58
+ "def": ["๐Ÿฅš", "an egg with something inside"]
59
+ }
60
+ }
61
+ ```
62
+
63
+ **Use words, not emoji.** `examples/skins/php.json` makes Python look a little like PHP: `def` becomes `function` and `None` becomes `null`. A skin like this can also make Python read like another human language.
64
+
65
+ ## Before you open a pull request
66
+
67
+ ```sh
68
+ python -m unittest discover -s tests
69
+ ```
70
+
71
+ The tests pick up every file in `pyskins/skins/` by themselves. You do not write a test for your skin.
72
+
73
+ ## Skins we would love to see
74
+
75
+ Pizza. A full Easter. Halloween. Space. Pirates. The ocean. Football. Cats. Music. Wizards. Python in your own language.
76
+
77
+ Or something nobody has thought of. Surprise us.
78
+
79
+ ## Add a fun program
80
+
81
+ The `examples/` folder is a small gallery: short programs, each one a `.py` file in emoji that runs. A new one is welcome too.
82
+
83
+ 1. Write a short program in normal Python. Make it print something, and do not ask the user to type.
84
+ 2. Put a skin on it: `pyskins apply christmas your_program.py -o examples/your_program.py`.
85
+ 3. Run it: `python examples/your_program.py`.
86
+ 4. Add a row to the table in the README.
87
+
88
+ ## Other help
89
+
90
+ Found a file that does not come back the same after `apply` and `undo`? That is the one bug this project must never have. Please open an issue and attach the file.
91
+
92
+ Everything here is under the MIT licence, and so is what you add.
pyskins-0.1.0/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Alex and Isabela Girlea
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.