pypa / sampleproject

A sample project that exists for PyPUG's "Tutorial on Packaging and Distributing Projects"

A sample Python project

A sample project that exists as an aid to the Python Packaging User Guide's Tutorial on Packaging and Distributing Projects.

This project does not aim to cover best practices for Python project development as a whole. For example, it does not provide guidance or tool recommendations for version control, documentation, or testing.

The source for this project is available here.

The metadata for a Python project is defined in the pyproject.toml file, an example of which is included in this project. You should edit this file accordingly to adapt this sample project to your needs.

---

This is the README file for the project.

The file should use UTF-8 encoding and can be written using reStructuredText or markdown with the appropriate key set. It will be used to generate the project webpage on PyPI and will be displayed as the project homepage on common code-hosting services, and should be written for that purpose.

Typical contents for this file would include an overview of the project, basic usage examples, etc. Generally, including the project changelog in here is not a good idea, although a simple “What's New” section for the most recent version may be appropriate.

sampleproject's Issues

bdist_wheel doesn't honour manifest.in and include_package_data

I modified setup.py with the latest recommendation to use MANIFEST.in and include_package_data=True: #30 (comment)

Here is my modification

$ git diff
diff --git a/setup.py b/setup.py
index fdb9202..68d443e 100644
--- a/setup.py
+++ b/setup.py
@@ -165,16 +165,13 @@ setup(
     #
     # If using Python 2.6 or earlier, then these have to be included in
     # MANIFEST.in as well.
-    package_data={  # Optional
-        'sample': ['package_data.dat'],
-    },
+    include_package_data=True,
 
     # Although 'package_data' is the preferred approach, in some case you may
     # need to place data files outside of your packages. See:
     # http://docs.python.org/3.4/distutils/setupscript.html#installing-additional-files
     #
     # In this case, 'data_file' will be installed into '<sys.prefix>/my_data'
-    data_files=[('my_data', ['data/data_file'])],  # Optional
 
     # To provide executable scripts, use entry points in preference to the
     # "scripts" keyword. Entry points provide cross-platform support and allow

Building sdist works fine:

$ git clean -ffdx
$ python setup.py sdist | grep data_file
copying data/data_file -> sampleproject-1.3.0/data
$

But bdist_wheel doesn't copy any data:

$ git clean -ffdx
$ python setup.py bdist_wheel | grep data_file
$ 

Checked the whl feel if it contains data_file in it. It doesn't contain either.

$ unzip dist/*.whl -d dist/unzipped
Archive:  dist/sampleproject-1.3.0-py2.py3-none-any.whl
  inflating: dist/unzipped/sample/__init__.py  
  inflating: dist/unzipped/sampleproject-1.3.0.dist-info/LICENSE.txt  
  inflating: dist/unzipped/sampleproject-1.3.0.dist-info/METADATA  
  inflating: dist/unzipped/sampleproject-1.3.0.dist-info/WHEEL  
  inflating: dist/unzipped/sampleproject-1.3.0.dist-info/entry_points.txt  
  inflating: dist/unzipped/sampleproject-1.3.0.dist-info/top_level.txt  
  inflating: dist/unzipped/sampleproject-1.3.0.dist-info/RECORD  

This is super confusing. :(

$ python --version
Python 3.6.6 :: Anaconda, Inc.

# versions:
setuptools=41.4.0
wheel=0.33.6

add install_requires

I think we have to include install_requires

neither package_data or data_files get installed

I have tried this on Python 2.7.5 and Python 3.4.3 and am unable to see package_data.dat or data_file installed anywhere when I do "python setup.py install"
If I change to distutils it works fine.

Add appveyor

Provide an appveyor.yml file.

Asking, cause it give me trouble with python 3.5 with long description as markdown.

Simplify .gitignore

I noticed that the .gitignore file has all sorts of references to things that aren't used in the sample project (probably because the file was auto-generated by GitHub).

I think it would make sense to tailor the .gitignore to what is actually used in the project.

Allow the project to be used as starting point for non-MIT licensed project

It seems like if one is starting a new project using the sample project as the "first commit," then the new project also has to be licensed using MIT (since the sample project is licensed using MIT).

Is there a way to license the sample project so that different licenses could be used for projects starting from it? Thanks.

request for fresh release

Please help me unblock pypi/warehouse#8011 by making and publishing a fresh release of sampleproject.

This would be (the first since November), so somewhat user-visible changes include:

• Switch to src/ layout #104
• Implement PEP 518 and opt into PEP 517 builds #101
• Drop support for EOL Python 2 #116
• Update sample author email #118
• Added python logo image to README.md inline #119

Somewhat less user-visible changes:

• Pass positional arguments to pytest #107
• Use tox-travis to simplify configuration #99
• Update check-manifest invocation #114
• Improve tests #121

video streamer is not working (pyzmq)

I'm using pyzmq from here, the following code working fine with single system(by using the same system ip or localhost).
when i tried to run the viewer file one system and another file in a different system then its didn't show anything.

Viewer.py
`
import cv2
import zmq
import base64
import numpy as np
context = zmq.Context()
footage_socket = context.socket(zmq.SUB)
footage_socket.bind('tcp://*:5555')
footage_socket.setsockopt_string(zmq.SUBSCRIBE, np.unicode(''))
while True:
try:
frame = footage_socket.recv_string()
img = base64.b64decode(frame)
npimg = np.fromstring(img, dtype=np.uint8)
source = cv2.imdecode(npimg, 1)
cv2.imshow("Live", source)
cv2.waitKey(1)

except KeyboardInterrupt:
    cv2.destroyAllWindows()
    break

`

Streamer.py

`import base64
import cv2
import zmq
import tkinter
from tkinter import *
master = Tk()
master.title("Video-c")
master.geometry('350x200')
userInput = StringVar()
ll = Label(master, text="IP Address:", font=("Arial", 10))
ll.config(height=2, width=15)
ll.place(x=15, y=65, height=18)
e1 = Entry(master, textvariable=userInput,width=20, font=("Arial", 12))
def connect(userInput):
IP=userInput.get()
context = zmq.Context()
footage_socket = context.socket(zmq.PUB)
footage_socket.connect('tcp://'+IP+':5555')

camera = cv2.VideoCapture(0)  # init the camera

while True:
    try:
        grabbed, frame = camera.read()  # grab the current frame
        frame = cv2.resize(frame, (640, 480))  # resize the frame
        encoded, buffer = cv2.imencode('.jpg', frame)
        jpg_as_text = base64.b64encode(buffer)
        footage_socket.send(jpg_as_text)

    except KeyboardInterrupt:
        camera.release()
        cv2.destroyAllWindows()
        break

e1.bind('', (lambda event: connect(userInput)))
e1.place(x=120, y=60, height=25)
ss = Button(text='connect', anchor='center', font=30, width=18, height=3, bd=0, command=(lambda: connect(userInput)))
act_img = PhotoImage(file='e1.png')
ss.config(image=act_img)
ss.place(x=200, y=110, height=68, width=68)
master.mainloop()`

setup.py imports its own package "sample"

In commit 335acdc, setup.py was made to import the very package it's meant to install. [There are issues with importing the package itself during installation, see Carl Meyer's post here (referenced in Issue #1) and a leading answer on Stack Overflow here.

Use pathlib instead of os.path

The setup.py file uses os.path functions instead of pathlib though only Python>=3.5 is supported.

Shall we use pathlib?

setup.py: test_suite

The line

test_suite='tests',

should be added to setup.py. Apparently, Python3.4 finds the tests even without that but Python2.7 does not.

docs in sampleproject missing

The sampleproject missing a sample for the documentation. Please add it.

New users don't know where to put the docs directory ....

The unit test cannot be run separately

Steps:

1. git clone https://github.com/pypa/sampleproject.git
2. cd sampleproject
3. python3 tests/test_simple.py or python -m unittest tests/test_simple.py
4. Output:

Traceback (most recent call last):
  File "tests/test_simple.py", line 7, in <module>
    from sample.simple import add_one
ModuleNotFoundError: No module named 'sample'

How am I supposed to run the tests classes individually?

Separator in the `keywords` argument of setup()

Hello,

According to this thread and that commit, it seems to me that with setuptools, the keywords argument of setup() expects a string containing a comma-separated list; however, the setup.py example in the PyPA sample project uses a string containing a space-separated list:

keywords='sample setuptools development'

Am I somehow mistaken? Besides, if comma-separated list is indeed the correct thing to use, it seems to me that it would be desirable to make it so that each item has spaces trimmed on both sides, so as to allow readable values such as "sample, setuptools, development", as opposed to "sample,setuptools,development". However, the setuptools docs seem rather vague in this department:

keywords: list-comma

(...)

list-comma: dangling list or string of comma-separated values

Thanks!

Drop Python 2.7 support

I think it's probably time to remove anything that's Python 2 specific from this example.

(cc @hugovk?)

Switch to setup.cfg for metadata?

Looking at the setuptools documentation, it seems that it's now possible to put project's metadata in setup.cfg (see http://setuptools.readthedocs.io/en/latest/setuptools.html#configuring-setup-using-setup-cfg-files). I don't know when this was introduced, but would it make sense to switch to this approach as the recommended method?

@jaraco Any comments? I don't know when this ability was introduced to setuptools, but it looks really easy to use, and (as far as I'm aware) didn't get as much publicity as maybe it should have...?

Help please: my first python package

Hi everyone,

I recently released a new Python Library (check here https://github.com/vertica/Vertica-ML-Python)
I followed the tutorial to allow PIP install and created the setup.py (I don't know if it is right)
I have inside the github page a folder named vertica_ml_python. I want that in the execution of
pip install vertica_ml_python it goes to https://github.com/vertica/Vertica-ML-Python and copy paste the folder in the user site-packages folder (and that is all)
If someone can help me I would be really grateful.

Best,

Badr

python 2/3 agnostic?

It is not clear if setup.py is aimed running both in python 2 and 3 (without 2to3 or 3to2).
It first find the version string with a codecs.open, that work in both; but the

open('DESCRIPTION.rst', encoding='utf-8') 

is python3 only. Wouldn't it be better to use the same policy?

Clarify Python 2 and 3 language

I think the sample project should be more explicit about its goals with respect to Python 2 and 3, for example in the main README.

Also, this language seems to imply that it's not good practice to write a project targeting only Python 3.

[bdist_wheel]
# This flag says that the code is written to work on both Python 2 and Python
#3. If at all possible, it is good practice to do this. If you cannot, you
# will need to generate wheels for each Python version that you support.
universal=1

I think that implication should be changed to say that "compatibility with Python 3 is good practice," because writing Python 3-only projects is also good for the community and shouldn't be discouraged.

Travis config appears to be wrong

The suggested Travis config fails when testing Python 3.x. As far as I can see, it runs all 3 tests under Python 2.7, even though the TOXENV variable is set to 3.x.

I don't know much about configuring Travis, but the following (stolen from pip) seems to work better:

matrix:
  include:
    - python: 2.7
      env: TOXENV=py27
    - python: 3.5
      env: TOXENV=py35
    - python: 3.6
      env: TOXENV=py36

Is that the right approach?

Change "Sample" to "Example"

Example vs. Sample

Add a pyproject.toml

As an indication of best practice, we should consider adding a pyproject.toml file.

packages no effect with ext_modules enabled.

Add foo.c in the root folder, then specify ext_modules in setup() method like ext_modules=[Extension('foo',['foo.c'])].
The generated wheel file by calling python setup.py bdist_wheel includes tests package.

Wrong comment on keywords?

According to Distutils' doc, keywords can be a list (preferred) or string. But the comment in sampleproject's setup.py says it must be a string.

Practice Runs

Sorry, Wrong project!

Demonstrate python_requires usage

It would be useful if the sample setup.py demonstrated how to use python_requires to describe the versions of Python your project supports.

I understand python_requires is a new feature of Pip, but I didn't realise it existed: I actually assumed that Pip used the Programming Lange :: Python classifiers to determine the Python versions supported, and published a "Python3-only" package which was still installable on Python 2 as a result.

It'd be useful if the sample demonstrated python_requires, and clarified that the classifiers are recommendations only (for humans to read), while python_requires is actually checked by Pip before installing.

Can this project be considered as the official or the standard form for create python packages?

it's more a question than a real issue, I know there are some alternatives based on cookiecutter for example, but can this be taked as a good starting point, or only serves as a reference for the Python Packaging Tutorial.

Thanks.

Update files to include Python 3.7

Add Python 3.7 to setup.py and tox.ini.

why "find_version"?

why "find_version" (that parses the file) vs just importing your package and using package.__version__.

I'm honestly unclear on that myself.

Demonstrate testing on multiple platforms (macOS/Windows)

A few ways this could be done:

• via GitHub actions
• via the existing Travis CI config
• via Appveyor

Setup.cfg uses deprecated license_file argument instead of license_files replacement

license_file is deprecated as of recent versions, replaced by license_files. Therefore, this line in setup.cfg needs to be updated to reflect that. I'd just make it myself, if it wasn't such a trivial change, though I still of course can if need be.

python setup.py test not working

The tests of the sampleproject don't get executed:

user@host> python setup.py test
running test

... nice: all tests pass?

No, since the test (unchanged) looks like this:

    def test_failure(self):
        self.assertTrue(False)

I am missing an exception if I run "python setup.py test".

I have no clue how the right way to fix this looks like.

add .pypirc file

It would be nice to see this file here as I ran into some snags. So have others: http://stackoverflow.com/questions/21823705/how-to-fix-the-issue-pypi-test-not-found-in-pypic-when-submit-package-to-pypi

how is this project connected to kafka rest client?

the Project link - homepage
for the project 'kafka-rest-client 0.8.0'
leads towards this repo

Not sure how this project is connected to kafka. Was that a typo?

package will be named src

Hi.

I've tried renaming the source directory name to 'src'. Installing the produced package will install the package in site-packages/src and sure enough, importing it requires import src rather than import package_name.

Publish this project on PyPI

It would be nice to automatically publish this project at https://pypi.org/project/sampleproject/ as it changes .

Expand on the testing directory

We should probably flesh out the tests directory a bit (although it's going to be hard to avoid getting into "my favourite test package" debates...)

• Does the tests directory need __init__.py? (Yes, for some test tools, so probably should be there).
• How are tests run? Will setup.py test work? Does anyone actually use that? Should we include a (cross-platform) test runner script?
• Do we need a note in README.txt recommending pip install -e when running tests, or should the test runner script just set sys.path?

I think we probably should recommend a testing package, specifically unittest. It's another one of those "give a basic recommendation that people can evaluate once they have experience" issues.

We need to sort out getting the tests directory into the sdist. The MANIFEST.in has a stab at it, but I'm not sure it works. I raised a question about this on pypa-dev (in the long thread on this project) but didn't get a satisfactory answer...

Bootstrap setuptools

Hi,

Setuptools recommends bootstraping using ez_setup.py:

http://pythonhosted.org/setuptools/using.html

yet this project does not do so. Given that one might have a valid Python installation which does not have setuptools, perhaps it would be a good idea to bootstrap?

I am not aware of any downsides- if they exist it would be nice if they were clearly documented.

Cheers,

Álex

add tox.ini and .travis.yml

many people use tox and travis, right?

maybe this is "feature creep" for the point of this project, but I don't know.
I'm inclined to add it.

DESCRIPTION.rst has relative path and breaks when installed from a remote directory

The original find_version function utilizes the here variable to ensure that the README.txt file can be found when setup.py is not run in the local directory.

This logic should apply to DESCRIPTION.rst as well. Without it, this breaks when using, for example, pip's VCS installation behavior.

It would be great to add a simple module and a test for that module.

This sample project is a very nice thing to finally have. I find most of the documentation of python project structure to be incomplete or opaque.

It would be great to add a very simple module and a test for that module. Just to see how the imports look.

Move main out of __init__

It'd probably be better to encourage people to keep __init__.py minimal.

just use a readme, not a description and readme file

see discussion here on distutils-sig

https://mail.python.org/pipermail/distutils-sig/2015-September/026900.html

Add graphic to README

Someone asked me today,

If I want to link to an example image in my readme.rst for viewing on pypi, should I bundle that in the package? Or just link it directly from github? Or...?

To illustrate this, let's add a Python logo file to this repo and use it in README.rst. Syntax would be like:

.. image:: https://github.com/pypa/sampleproject/raw/master/docs/image/logo.png
    :alt: Python logo

Example for executable script is missing

Hi, I am missing an example how to package an executable script.

Imagine you have mygrep.py the world best grep replacement.

How to structure the files and directories?

AFAIK the script (here mygrep.py) is almost empty. It just imports from the library and calls its main() method.

A simple example inside this sampleproject would be nice.

Should the installed package include LICENSE.txt?

The packaging guide suggests that the license file itself should be distributed as part of the package, but it doesn't look like the sample project does this.

We've been asked to distribute a license file in HypothesisWorks/hypothesis#1311, but neither package_data nor data_files seem like a good way to do this, so I thought it was worth checking here 😄

Universal wheels mentioned in docs, but this project does not use them

From https://packaging.python.org/guides/distributing-packages-using-setuptools/#universal-wheels:

You can also permanently set the --universal flag in setup.cfg (e.g., see sampleproject/setup.cfg)

This project's setup.cfg no longer specifies --universal given dropped support for EOL py2.

Should the PyPA docs be changed?

Not PEP8

flake8 sampleproject/setup.py
sampleproject/setup.py:1:1: D100  Missing docstring in public module
sampleproject/setup.py:1:80: E501 line too long (86 > 79 characters)
sampleproject/setup.py:65:80: E501 line too long (80 > 79 characters)
sampleproject/setup.py:71:80: E501 line too long (82 > 79 characters)
sampleproject/setup.py:74:19: E251 unexpected spaces around keyword / parameter equals
sampleproject/setup.py:74:21: E251 unexpected spaces around keyword / parameter equals
sampleproject/setup.py:88:80: E501 line too long (91 > 79 characters)

The other items are not expected to be used verbatim, but it doesn't set a good example.

flake8 sampleproject/setup.py
sampleproject/setup.py:1:1: D100  Missing docstring in public module
sampleproject/setup.py:1:80: E501 line too long (86 > 79 characters)
sampleproject/setup.py:65:80: E501 line too long (80 > 79 characters)
sampleproject/setup.py:71:80: E501 line too long (82 > 79 characters)
sampleproject/setup.py:74:19: E251 unexpected spaces around keyword / parameter equals
sampleproject/setup.py:74:21: E251 unexpected spaces around keyword / parameter equals
sampleproject/setup.py:88:80: E501 line too long (91 > 79 characters)

Travis doesn’t run on pull requests

I noticed that my PR #87 didn’t get tested on Travis. Apparently, the last PR to be tested was #71 and then #74 wasn’t, so something happend between April 26 and June 5, 2018.

setup.py sdist fails with UnicodeDecodeError (py2.7)

I started using sampleproject as a skeleton for a small project of mine, I got the following error when doing python setup.py sdist:

....
Creating tar archive
Traceback (most recent call last):
  File "setup.py", line 100, in <module>
    'sample=sample:main',
  File "/System/Library/Frameworks/Python.framework/Versions/2.7/lib/python2.7/distutils/core.py", line 152, in setup
    dist.run_commands()
  File "/System/Library/Frameworks/Python.framework/Versions/2.7/lib/python2.7/distutils/dist.py", line 953, in run_commands
    self.run_command(cmd)
  File "/System/Library/Frameworks/Python.framework/Versions/2.7/lib/python2.7/distutils/dist.py", line 972, in run_command
    cmd_obj.run()
  File "/Users/stefaan/tmp/python-packaging-playground/sampleproject/ve/lib/python2.7/site-packages/setuptools-0.6c11-py2.7.egg/setuptools/command/sdist.py", line 147, in run
  File "/System/Library/Frameworks/Python.framework/Versions/2.7/lib/python2.7/distutils/command/sdist.py", line 451, in make_distribution
    owner=self.owner, group=self.group)
  File "/System/Library/Frameworks/Python.framework/Versions/2.7/lib/python2.7/distutils/cmd.py", line 392, in make_archive
    owner=owner, group=group)
  File "/System/Library/Frameworks/Python.framework/Versions/2.7/lib/python2.7/distutils/archive_util.py", line 237, in make_archive
    filename = func(base_name, base_dir, **kwargs)
  File "/System/Library/Frameworks/Python.framework/Versions/2.7/lib/python2.7/distutils/archive_util.py", line 101, in make_tarball
    tar = tarfile.open(archive_name, 'w|%s' % tar_compression[compress])
  File "/System/Library/Frameworks/Python.framework/Versions/2.7/lib/python2.7/tarfile.py", line 1687, in open
    _Stream(name, filemode, comptype, fileobj, bufsize),
  File "/System/Library/Frameworks/Python.framework/Versions/2.7/lib/python2.7/tarfile.py", line 431, in __init__
    self._init_write_gz()
  File "/System/Library/Frameworks/Python.framework/Versions/2.7/lib/python2.7/tarfile.py", line 459, in _init_write_gz
    self.__write(self.name + NUL)
  File "/System/Library/Frameworks/Python.framework/Versions/2.7/lib/python2.7/tarfile.py", line 475, in __write
    self.buf += s
UnicodeDecodeError: 'ascii' codec can't decode byte 0x8b in position 1: ordinal not in range(128)

I fired up my debugger (my setup: Python 2.7.2 in a virtualenv on Mac OS X 10.8.5), and traced the issue back to find_version in setup.py:

def find_version(*file_paths):
    with codecs.open(os.path.join(here, *file_paths), 'r', 'latin1') as f:
        version_file = f.read()
    version_match = re.search(r"^__version__ = ['\"]([^'\"]*)['\"]",
                              version_file, re.M)
    if version_match:
        return version_match.group(1)

It returns the version as a unicode string, and in the tarfile logic this unicode string is added to a raw string, resulting in the UnicodeDecodeError: 'ascii' codec can't decode issue .

I can fix it for me by encoding the unicode string to a raw string:

return str(version_match.group(1))
# or 
return version_match.group(1).encode('ascii')

not sure though if this is the right approach