I have created a package on github django-joyride, after publishing it to pypi it is not showing the README.rst properly. I have checked my syntax here on an online viewer and you can see it works fine. What could be the issue?
I had the same problem when uploading my python module to pypi .
Later I checked the README.rst for errors using rst-lint which showed that my readme file was right. You can also use restructuredtext_link package for python to check the rst file for any errors or warnings .
I found that the problem was not in the README file but in setup.py itself.
Follow the below points while writing Readme and setup.py
DO NOT WRITE MULTI LINE python strings for description or summary or anything that goes into the setup( ) arguments .
Don't use relative links in the README file .(like ./path1/path2 ).
Make sure the rst syntax is all right using a checking tool like rst-lint.
If you have a markdown file , you can convert it to Restructured text using pandoc easily.
Also do not use any new docutils syntax since Pypi doesn't use the latest version as Github does.
It could be that pypi gets confused because you have both a README.md and a README.rst file. Try to delete the .md one; github can handle README.rst fine.
Related
I would like to read the "version" from a file
# The "version" is no longer taken from here but rather from the "version" file
version = "0.3.13" # This should be read from a file..
How can this be done inside the pyproject.toml .. or is that not possible? If not possible is there a way to read the contents from a file into a variable inside the pyproject.toml? Ultimately is that file just static ?
toml is a static file format. See https://toml.io So there is no way to read content from a different place.
Because you are talking about pyproject.toml and version I guess your goal is to have single source of truth for the version number of your python project, so that it can be used during runtime. If so the correct way to do it, to have the version in the pyproject.toml. Once the project is installed you can use importlib.metadata to get the version number in your program:
import importlib.metadata
version = importlib.metadata.version("my-package")
There are two version of my little tool:
https://pypi.python.org/pypi/tbzuploader/2017.11.0
https://pypi.python.org/pypi/tbzuploader/2017.12.0 Bug: The pypi page looks ugly.
In the last update a change in README.rst cases a warning:
user#host> rst2html.py README.rst > /tmp/foo.html
README.rst:18: (WARNING/2) Inline emphasis start-string without end-string.
README.rst:18: (WARNING/2) Inline emphasis start-string without end-string.
Now the pypi page looks ugly :-(
I use this recipe to do CI, bumpversion, upload to pypi: https://github.com/guettli/github-travis-bumpversion-pypi
How could I ensure that no broken README.rst gets released any more? With other words I want to avoid that the pypi page looks ugly.
Dear detail lovers: Please don't look into the current particular error in the README.rst. That's is not the question :-)
Update
As of Sep 21, 2018, the Python Packaging Authority recommends an alternative command twine check. To install twine:
pip install twine
twine check dist/*
Note that twine requires readme_renderer. You could still use readme_renderer, and you only need to install twine if you want its other features, which is a good idea anyway if you are releasing to PyPI.
From the official Python packaging docs, Uploading your Project to PyPI:
Tip: The reStructuredText parser used on PyPI is not Sphinx! Furthermore, to ensure safety of all users, certain kinds of URLs and directives are forbidden or stripped out (e.g., the .. raw:: directive). Before trying to upload your distribution, you should check to see if your brief / long descriptions provided in setup.py are valid. You can do this by following the instructions for the pypa/readme_renderer tool.
And from that tool's README.rst:
To check your long description's locally simply install the readme_renderer library using:
$ pip install readme_renderer
$ python setup.py check -r -s
Preamble
I had a readme which would not render on PyPi, other than the first element on the page (an image). I ran the file against multiple validators, and tested it against other renders. It worked perfectly fine everywhere else! So, after a long, nasty fight with it, and numerous version bumps so I could test a PyPi revision, I tried reducing the file to a bare minimum, from which I'd build it back up. It turned out that the first line was always processed, and then nothing else was...
Solution
Discovering this clue regarding the first line, I then had an epiphany... All I had to do was change the line endings in the file! I was editing the file in Windows, with Windows line endings being tacked on implicitly. I changed that to Unix style and (poof!) PyPi fully rendered the doc!
Rant...
I've encountered such things in the past, but I took it for granted that PyPi would handle cross platform issues like this. I mean one of the key features of Python is being cross platform! Am I the first person working in Windows to encounter this?! I don't appreciate the hours of time this wasted.
You could try if rstcheck catches the type of error in your readme. If it does, run it after pytest in your script section. (and add it in your requirements ofc).
I'm trying to get Read the Docs to generate the py-modindex.html file. Research into this question lead me to the following setup:
setup.py in the project directory has the following contents, which were the minimum needed to get pytest to work and haven't been changed since I got that part of my project working:
import setuptools
setuptools.setup(
name='polygons',
packages=setuptools.find_packages(),
)
docs/requirements.txt contains a single line:
sphinx-autodoc-annotation
The Read the Docs repository URL points to my GitHub repository.
The RtD setting for "Install your project inside a virtualenv using setup.py install" is checked.
The RtD setting for "Requirements file" points to docs/requirements.txt.
The "Module Index" link gets included in index.html, but the py-modindex.html file is missing.
My understanding is that with the virtualenv setting above, RtD will use the setup.py file to install the project so that Sphinx can read the documentation found in the Python docstrings. I'm using function annotations and would like sphyinx-autodoc-annotation to make use of those when creating the built docs files. All of this works splendidly on my local machine when I run make html while in the docs folder. Now I'm trying to get it to work on Read the Docs.
Note: This is an exercise I'm going through to understand everything before I apply it to my real project, which the polygons project is a placeholder for.
I'm trying to distribute web assets along with a web app that I'm trying to package, but I'm failing miserably. I don't understand why I have a different list of files installed or packages when I run bdist, sdist, or install.
Project Layout
The project runs with python 3 on Arch. The results are the same with Py3 on Raspbian.
I've done a very trimmed down version to make things simpler, which I describe here.
The files layout is as follow :
data/index.html
MANIFEST.in
mylib.py
setup.py
The MANIFEST.in file is :
recursive-include data *
The setup.py is :
#!/usr/bin/env python
from setuptools import setup, find_packages
setup(name='mylib',
version='0.1.2',
url='http://www.example.org',
author='Foo',
packages=find_packages(),
data_files = [ ('share/mylib', ['data/index.html']) ]
)
My goal is to install index.html in PREFIX/share/mylib/index.html.
Running setup.py
Now, bdist includes the file at the seemingly right location, while sdist and install just ignore it :
bdist
Using bdist, I have the following files in the resulting tar :
./usr/lib/python3.3/site-packages/mylib-0.1.2-py3.3.egg-info/SOURCES.txt
./usr/lib/python3.3/site-packages/mylib-0.1.2-py3.3.egg-info/top_level.txt
./usr/lib/python3.3/site-packages/mylib-0.1.2-py3.3.egg-info/dependency_links.txt
./usr/lib/python3.3/site-packages/mylib-0.1.2-py3.3.egg-info/PKG-INFO
./usr/share/mylib/index.html
This is exactly what I want to be installed, perfect. However, I really want sdist and install to work, since I want to distribute this thing on PyPI and be able to install from source checkouts.
sdist
When I untar the sdist file, everything seems ok and data is included :
...
mylib-0.1.2/data/
mylib-0.1.2/data/index.html
...
However, if I sudo python setup.py install --record=log.txt in the directory where it is untarred, the only file listed in the log is /usr/lib/python3.3/site-packages/mylib-0.1.2-py3.3.egg. No trace of data/index.html anywhere ('/usr/local/share', '/usr/share')
install
Same issue as sdist (I suppose this is expected). No trace of data/index.html anywhere ('/usr/local/share', '/usr/share').
I also tried to add a setup.cfg like this :
[install]
install-data=/usr/local/share/mylib/
install_data=/usr/local/share/mylib/
(I've added both install-data and install_data since docs state to use the later, while I saw other projects using the former). No luck.
Epilogue
Now, I quite new to python and it's environment, I'm probably missing something obvious or misunderstanding how setuptools works. I've been reading the doc back an forth, reading stackoverflow's Q&A in data_files at great length, but didn't make any progress.
If someone could point me to the right direction to solve this, this would be great. A link to a simple project distributing assets would be a good read too. I just couldn't find one that gave me that "Ah ah!" moment.
Thanks for reading.
I don't know whether this helps, as I always include my data files relative to the python packages they go with. Additionally to the MANIFFEST.in, you'd have a package_data key in setup.py:
setup(name='mylib',
version='0.1.2',
url='http://www.example.org',
author='Foo',
packages=find_packages(),
package_data={'package_name': 'package_dir/data/*'}
)
this would put the data to site-packages/mylib-0.1.2/data
i wrote a little module and i would like to know what are the basic steps to package it in order to send it to pypi:
what is the file hierarchy?
how should i name files?
should i use distutils to create PKG-INFO?
where should i include my documentation (made with sphinx)?
I recommend reading The Hitchhiker's Guide to Packaging. Specifically, you should look at the Quick Start section, which describes how to:
Lay out your project
Describe your project
Create your first release
Register your package with the Python Package Index (PyPI)
Upload your release, then grab your towel and save the Universe!
You should also look at the Current State of Packaging in the Introduction to Packaging section, as this helps untangle some of the confusion surrounding setuptools, distutils, distutils2, and distribute.
Update Re: How to Name Files
The excerpt below is from PEP8, which answers your question about how to name files:
Modules should have short, all-lowercase names. Underscores can be used in the module name if it improves readability. Python packages should also have short, all-lowercase names, although the use of underscores is discouraged.
Since module names are mapped to file names, and some file systems are case insensitive and truncate long names, it is important that module names be chosen to be fairly short -- this won't be a problem on Unix, but it may be a problem when the code is transported to older Mac or Windows versions, or DOS.
an example is always the best way to see how to do:
http://packages.python.org/an_example_pypi_project/
Maybe this CheeseShopTutorial is of help for you. From there:
Submitting Packages to the Package
Index
If you have some Python modules or packages that you would like to
share with the Python community, we'd love to have them included in
the Python Package Index! First, if you haven't done so, you will want
to get your project organized. You might follow the guidelines at
ProjectFileAndDirectoryLayout. After that, you'll want to read the
Python documentation regarding creating distributions:
http://docs.python.org/distutils/index.html.
You can also check Writing a Package in Python by Tarek Ziadé from Tarek's book "Expert Python Programming" where questions about development and distribution are addressed in great detail
Matthew Rankin's answer tells you how to organize your project file heirarchy, but I find myself having to look up the commands to execute every time I want to update a project on PyPI. So here they are:
As described on the PyPi site:
Create a setup.py file (here's an example)
Register a username/password with PyPi
Do this:
python setup.py sdist
python setup.py bdist_wheel
python setup.py register
twine upload dist/*
Look for your package on the PyPi site:
https://pypi.python.org/pypi?%3Aaction=index
On another machine try running:
pip install [your package name]
Most important thing is prepare your setup.py properly. Then:
setup.py sdist bdist_wheel to generate distribution archives to dist/ folder
twine upload dist/* to upload the archives to PyPi (with your PyPi username/password)
Here is an example of setup.py:
from setuptools import setup, find_packages
with open('README.md') as readme_file:
README = readme_file.read()
with open('HISTORY.md') as history_file:
HISTORY = history_file.read()
setup_args = dict(
name='elastictools',
version='0.1.2',
description='Useful tools to work with Elastic stack in Python',
long_description_content_type="text/markdown",
long_description=README + '\n\n' + HISTORY,
license='MIT',
packages=find_packages(),
author='Thuc Nguyen',
author_email='gthuc.nguyen#gmail.com',
keywords=['Elastic', 'ElasticSearch', 'Elastic Stack', 'Python 3', 'Elastic 6'],
url='https://github.com/ncthuc/elastictools',
download_url='https://pypi.org/project/elastictools/'
)
install_requires = [
'elasticsearch>=6.0.0,<7.0.0',
'jinja2'
]
if __name__ == '__main__':
setup(**setup_args, install_requires=install_requires)
You can find more detail tutorial here: https://medium.com/#thucnc/how-to-publish-your-own-python-package-to-pypi-4318868210f9