Hacktoberfest 2026: the issues maintainers tagged for October, open and beginner-friendly. Browse Hacktoberfest issues

Doc: Improve examples with use cases

Open
  • Is something wrong?
#258 2 comments 1 reaction 0 assignees View on GitHub

Maintainers usually reply within 1 day

Nobody has claimed this yet.

Assessment

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

Research direction

Review the existing “A toy example,” “A complete example,” and “More real world examples” sections to understand their progression. Done means adding a use-case section covering plugin discovery in directories, explaining when each example is useful, and recommending how to structure specifications and implementations.

Written by the indexing model from the issue text.

Description

Situation

Thanks for this wonderful project! 👍 I'm slowly understanding it. 😉

Maybe others has the same difficulties than I. Although I really appreciate the examples, it was still a bit hard to follow. IMHO, the current approach has a gap between "A complete example" and "More real world examples".

It misses one use case which is needed most: having a bunch of plugin files in a specific directory and how to structure and use them with pluggy. I think, this is quite common and it should be covered.

Additionally, it would be helpful to share some "best practices". For example, how to structure and where to place specification and implementation.

Proposal

So my proposal would be to add a new section to fill this gap. Depending on whether you like this approach, we could go a little bit further. So here is a more ambitious change.

IMHO, I would propose the following structure:

  • Use Cases
    • Creating a Simple Example
      That would be basically the content from the section "A toy example". Basically, it adds specification and implementation in one file.
    • Separating Specification and Implementation in Different Files
      That would be the content from "A complete example".
    • Discovering Plugins in Directories
      => That would be the new one
    • More real world examples

As you can see, the difficulty of the examples grow from easy to difficult.

Additionally, I would suggest:

  • add a small paragraph when the respective example is most beneficial. For example, if you need to load the plugins dynamically, you would probably not use the simplest example.
  • give recommendations how to structure your code and where to place specification and implementation. I think, this is not always clear from the text.

I would be happy to add a first draft if you consider this issue to be useful. 😉

Dominant language
Python
Stars
1.7k
Forks
170
Avg merge
1d 23h
Merged PRs (30d)
16

Getting set up

This project ships no dev container, Dockerfile or contributing guide, so setting up is up to you: start from its README, and see our first-contribution guide for the general steps.

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.

More from pytest-dev/pluggy

All issues in pytest-dev/pluggy

Similar issues

More Python issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.