8000 README update and code quality checks (#2202) · pyscript/pyscript@af06bc4 · GitHub
[go: up one dir, main page]
Skip to content

Commit af06bc4

Browse files
ntollntoll
authored
README update and code quality checks (#2202)
* README updates. * Ensure pre-commit black args match those in Makefile. * Ensure pre-commit and requirements versions align, and the commands run are the same in pre-commit and Makefile. * Update README files to reflect recent changes. Where possible, remove duplication and point to the official docs. * Run format and pre-commit prettifier on code. * Remove isort - it causes more trouble than is justified. * Ensure usage examples in the README.
1 parent 6fab9a1 commit af06bc4

File tree

6 files changed

+329
-259
lines changed

6 files changed

+329
-259
lines changed

‎.pre-commit-config.yaml

Lines changed: 1 addition & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -28,7 +28,7 @@ repos:
2828
rev: 24.8.0
2929
hooks:
3030
- id: black
31-
exclude: core/src/stdlib/pyscript/__init__\.py
31+
args: ["-l", "88", "--skip-string-normalization"]
3232

3333
- repo: https://github.com/codespell-project/codespell
3434
rev: v2.3.0
@@ -44,10 +44,3 @@ repos:
4444
- id: prettier
4545
exclude: core/test|core/dist|core/types|core/src/stdlib/pyscript.js|pyscript\.sw/|core/src/3rd-party
4646
args: [--tab-width, "4"]
47-
48-
- repo: https://github.com/pycqa/isort
49-
rev: 5.13.2
50-
hooks:
51-
- id: isort
52-
name: isort (python)
53-
args: [--profile, black]

‎Makefile

Lines changed: 6 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -9,6 +9,7 @@ PY_OK := $(shell python3 -c "print(int($(PY3_VER) >= $(MIN_PY3_VER)))")
99
all:
1010
@echo "\nThere is no default Makefile target right now. Try:\n"
1111
@echo "make setup - check your environment and install the dependencies."
12+
@echo "make update - update dependencies."
1213
@echo "make clean - clean up auto-generated assets."
1314
@echo "make build - build PyScript."
1415
@echo "make precommit-check - run the precommit checks (run eslint)."
@@ -57,6 +58,11 @@ clean:
5758
build:
5859
cd core && npx playwright install chromium && npm run build
5960

61+
# Update the dependencies.
62+
update:
63+
cd core && npm update && cd ..
64+
python -m pip install -r requirements.txt --upgrade
65+
6066
# Run the precommit checks (run eslint).
6167
precommit-check:
6268
pre-commit run --all-files
@@ -76,7 +82,6 @@ fmt-check: fmt-py-check
7682
# Format Python code.
7783
fmt-py:
7884
black -l 88 --skip-string-normalization .
79-
isort --profile black .
8085

8186
# Check the format of Python code.
8287
fmt-py-check:

‎README.md

Lines changed: 62 additions & 74 deletions
Original file line numberDiff line numberDiff line change
@@ -1,97 +1,85 @@
11
# PyScript
22

3-
## What is PySc 8000 ript
3+
## PyScrcipt is an open source platform for Python in the browser.
44

5-
### Summary
5+
Using PyScript is as simple as:
66

7-
PyScript is a framework that allows users to create rich Python applications in the browser using HTML's interface and the power of [Pyodide](https://pyodide.org/en/stable/), [MicroPython](https://micropython.org/) and [WASM](https://webassembly.org/), and modern web technologies.
7+
```html
8+
<!doctype html>
9+
<html lang="en">
10+
<head>
11+
<meta charset="utf-8" />
12+
<meta name="viewport" content="width=device-width,initial-scale=1" />
13+
<title>PyScript!</title>
14+
<link
15+
rel="stylesheet"
16+
href="https://pyscript.net/snapshots/2024.9.2/core.css"
17+
/>
18+
<script
19+
type="module"
20+
src="https://pyscript.net/snapshots/2024.9.2/core.js"
21+
></script>
22+ </head>
23+
<body>
24+
<!-- Use MicroPython to evaluate some Python -->
25+
<script type="mpy" terminal>
26+
print("Hello, world!")
27+
</script>
28+
</body>
29+
</html>
30+
```
31+
32+
PyScript enables the creation of rich Python applications in the browser using
33+
[Pyodide](https://pyodide.org/en/stable/) (a version of
34+
[CPython](https://python.org/)), [MicroPython](https://micropython.org/),
35+
[WASM](https://webassembly.org/), and modern web technologies. It means Python
36+
now runs anywhere a browser runs: desktop, laptop, mobile, tablet, or any other
37+
browser enabled B421 device.
838

9-
To get started see the [Beginning PyScript tutorial](https://docs.pyscript.net/latest/beginning-pyscript/).
39+
To start building, read the
40+
[Beginning PyScript tutorial](https://docs.pyscript.net/latest/beginning-pyscript/).
1041

11-
For examples see [here](https://pyscript.com/@examples).
42+
For example applications, see [here](https://pyscript.com/@examples).
1243

1344
Other useful resources:
1445

46+
- Our [Home Page](https://pyscript.net/) as an open source project.
1547
- The [official technical docs](https://docs.pyscript.net/).
16-
- Our current [Home Page](https://pyscript.net/) on the web.
17-
- A free-to-use [online editor](https://pyscript.com/) for trying PyScript.
18-
- Our community [Discord Channel](https://discord.gg/BYB2kvyFwm), to keep in touch .
48+
- A [YouTube channel](https://www.youtube.com/@PyScriptTV) with helpful videos
49+
and community content.
50+
- A free-to-use [online IDE](https://pyscript.com/) for trying PyScript.
51+
- Our community [Discord Channel](https://discord.gg/BYB2kvyFwm), to keep in
52+
touch .
1953

20-
Every Tuesday at 15:30 UTC there is the _PyScript Community Call_ on zoom, where we can talk about PyScript development in the open. Most of the maintainers regularly participate in the call, and everybody is welcome to join.
54+
Every Tuesday at 15:30 UTC there is the _PyScript Community Call_ on zoom,
55+
where we can talk about PyScript development in the open. Most of the
56+
maintainers regularly participate in the call, and everybody is welcome to
57+
join. This meeting is recorded and uploaded to our YouTube channel.
2158

22-
Every other Thursday at 16:00 UTC there is the _PyScript FUN_ call: this is a call in which everybody is encouraged to show what they did with PyScript.
59+
Every other Thursday at 16:00 UTC there is the _PyScript FUN_ call: the focus
60+
of this call is to share fun projects, goofy hacks or clever uses of PyScript.
61+
It's a supportive, energetic and entertaining meeting. This meeting is also
62+
recorded and uploaded to our YouTube channel.
2363

24-
For more details on how to join the calls and up to date schedule, consult the official calendar:
64+
For more details on how to join the calls and up to date schedule, consult the
65+
official calendar:
2566

2667
- [Google calendar](https://calendar.google.com/calendar/u/0/embed?src=d3afdd81f9c132a8c8f3290f5cc5966adebdf61017fca784eef0f6be9fd519e0@group.calendar.google.com&ctz=UTC) in UTC time;
2768
- [iCal format](https://calendar.google.com/calendar/ical/d3afdd81f9c132a8c8f3290f5cc5966adebdf61017fca784eef0f6be9fd519e0%40group.calendar.google.com/public/basic.ics).
2869

29-
### Longer Version
30-
31-
PyScript is a meta project that aims to combine multiple open technologies into a framework that allows users to create sophisticated browser applications with Python. It integrates seamlessly with the way the DOM works in the browser and allows users to add Python logic in a way that feels natural both to web and Python developers.
32-
33-
## Try PyScript
34-
35-
To try PyScript, import the appropriate pyscript files into the `<head>` tag of your html page:
36-
37-
```html
38-
<head>
39-
<link
40-
rel="stylesheet"
41-
href="https://pyscript.net/releases/2024.8.2/core.css"
42-
/>
43-
<script
44-
type="module"
45-
src="https://pyscript.net/releases/2024.8.2/core.js"
46-
></script>
47-
</head>
48-
<body>
49-
<script type="py" terminal>
50-
from pyscript import display
51-
display("Hello World!") # this goes to the DOM
52-
print("Hello terminal") # this goes to the terminal
53-
</script>
54-
</body>
55-
```
70+
## Contribute
5671

57-
You can then use PyScript components in your html page. PyScript currently offers various ways of running Python code:
72+
For technical details of the code, please see the [README](core/README) in the
73+
`core` directory.
5874

59-
- `<script type="py">`: can be used to define python code that is executable within the web page.
60-
- `<script type="py" src="hello.py">`: same as above, but the python source is fetched from the given URL.
61-
- `<script type="py" terminal>`: same as above, but also creates a terminal where to display stdout and stderr (e.g., the output of `print()`); `input()` does not work.
62-
- `<script type="py" terminal worker>`: run Python inside a web worker: the terminal is fully functional and `input()` works.
63-
- `<py-script>`: same as `<script type="py">`, but it is not recommended because if the code contains HTML tags, they could be parsed wrongly.
64-
- `<script type="mpy">`: same as above but use MicroPython instead of Python.
75+
Read the [contributing guide](https://docs.pyscript.net/latest/contributing/)
76+
to learn about our development process, reporting bugs and improvements,
77+
creating issues and asking questions.
6578

66-
Check out the [official docs](https://docs.pyscript.net/) for more detailed documentation.
67-
68-
## How to Contribute
69-
70-
Read the [contributing guide](https://docs.pyscript.net/latest/contributing/) to learn about our development process, reporting bugs and improvements, creating issues and asking questions.
71-
72-
Check out the [developing process](https://docs.pyscript.net/latest/developers/) documentation for more information on how to setup your development environment.
73-
74-
For technical details of the code, please see the [README](pyscript.core/README) in `pyscript.core`.
79+
Check out the [developing process](https://docs.pyscript.net/latest/developers/)
80+
documentation for more information on how to setup your development environment.
7581

7682
## Governance
7783

78-
The [PyScript organization governance](https://github.com/pyscript/governance) is documented in a separate repository.
79-
80-
## Release
81-
82-
To cut a new release of PyScript simply
83-
[add a new release](https://github.com/pyscript/pyscript/releases) while
84-
remembering to write a comprehensive changelog. A [GitHub action](https://github.com/pyscript/pyscript/blob/main/.github/workflows/publish-release.yml)
85-
will kick in and ensure the release is described and deployed to a URL with the
86-
pattern: https://pyscript.net/releases/YYYY.M.v/ (year/month/version - as per
87-
our [CalVer](https://calver.org/) versioning scheme).
88-
89-
Then, the following three separate repositories need updating:
90-
91-
- [Documentation](https://github.com/pyscript/docs) - Change the `version.json`
92-
file in the root of the directory and then `node version-update.js`.
93-
- [Homepage](https://github.com/pyscript/pyscript.net) - Ensure the version
94-
referenced in `index.html` is the latest version.
95-
- [PSDC](https://pyscript.com) - Use discord or Anaconda Slack (if you work at
96-
Anaconda) to let the PSDC team know there's a new version, so they can update
97-
their project templates.
84+
The [PyScript organization governance](https://github.com/pyscript/governance)
85+
is documented in a separate repository.

0 commit comments

Comments
 (0)
0