pypa / pypa/packaging.python.org

Document warnings on how to set (long_)description

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

Nobody has claimed this yet.

Dominant language
Python
Stars
1.7k
Forks
1.7k
Avg merge
3d 12h
Merged PRs (30d)
4

Description

I have just spent >= 1 hour to overcome this bug: https://github.com/pypa/twine/issues/454

  • In the description argument passed to setup(...), you must not pass newlines!

    (Especially I passed __doc__, which starts of course with a newline most of the time.)
  • In the long_description argument passed to setup(...), you must use LF newlines (\n) exclusively. (No \n! No \r!)

    I suggest doing
    # Open readme with original (i.e. LF) newlines
    # to prevent the all too common "`long_description_content_type` missing"
    # bug (https://github.com/pypa/twine/issues/454)
    with open('README.md', 'r', newline='', encoding='utf-8') as readme_file:
    	long_description = readme_file.read()
    	long_description_content_type = 'text/markdown'
    
    setup(
    	# ...
    	long_description = long_description,
    	long_description_content_type = long_description_content_type,
    )
    

This should be documented in https://packaging.python.org/tutorials/packaging-projects/.

Contributor guide

No contributing guide indexed for this repository

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

Start with the packaging-projects tutorial named in the issue and review the linked Twine issue for the reported behavior. Done means the tutorial documents the description and long_description newline requirements and includes guidance for setting long_description_content_type.

Written by the indexing model from the issue text.

Assessment

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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.