pyscript / pyscript/docs

Missing Documentation - I/O behaviour

Open
#157 0 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Dominant language
Python
Stars
17
Forks
20
PR merge metrics
No merged PRs in 30d

Description

Background

At the moment it is difficult to jump right into a PyScript project and understand what the behavior of some things will be. For example, if I use print or the the logging module without any configuration, it would be helpful to know where the print statements will end up writing. With some context it is clear that the behaviour can differ depending on if the terminal is active.

Problem

The documentation does not explain basic I/O behaviors of common outputs like logging or print. A developer may expect anything printed to go to the web console. It's only through testing that they find out that the if you write to stderr or submit a logger.error message via the Python Logging library that you will observe that a div will be added to the document of class py-error, and if you want to disable or overwrite this behaviour you need to refer to the error plugin (see #156).

Proposal

Create a section that explains how Python IO and logging maps into the web console and other features, like the error plugin.

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Review the existing error plugin documentation referenced by #156 and the documentation structure for an appropriate place to add the section. Explain how print, stderr, and Python logging appear with and without the terminal, including the py-error behavior and how the error plugin changes it.

Written by the indexing model from the issue text.

Assessment

Tech stack
python
Domain
documentation
Issue type
Documentation
Difficulty
3/5
Estimated time
1-2 days
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.