You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Remove link to third party cookiecutter template (encode#7902)
The template has not been maintained for six years, so it's out of date on versions and various "best practices" (e.g. pre-commit). I also think any template should be documented on its own repo rather than here, especially if it's not an official maintained project.
Copy file name to clipboardExpand all lines: docs/community/third-party-packages.md
+2-135Lines changed: 2 additions & 135 deletions
Original file line number
Diff line number
Diff line change
@@ -14,142 +14,9 @@ We aim to make creating third party packages as easy as possible, whilst keeping
14
14
15
15
If you have an idea for a new feature please consider how it may be packaged as a Third Party Package. We're always happy to discuss ideas on the [Mailing List][discussion-group].
16
16
17
-
## How to create a Third Party Package
17
+
## Creating a Third Party Package
18
18
19
-
### Creating your package
20
-
21
-
You can use [this cookiecutter template][cookiecutter] for creating reusable Django REST Framework packages quickly. Cookiecutter creates projects from project templates. While optional, this cookiecutter template includes best practices from Django REST framework and other packages, as well as a Travis CI configuration, Tox configuration, and a sane setup.py for easy PyPI registration/distribution.
22
-
23
-
Note: Let us know if you have an alternate cookiecutter package so we can also link to it.
24
-
25
-
#### Running the initial cookiecutter command
26
-
27
-
To run the initial cookiecutter command, you'll first need to install the Python `cookiecutter` package.
28
-
29
-
$ pip install cookiecutter
30
-
31
-
Once `cookiecutter` is installed just run the following to create a new project.
github_username (default is "yourname")? jappleseed
40
-
pypi_project_name (default is "dj-package")? djangorestframework-custom-auth
41
-
repo_name (default is "dj-package")? django-rest-framework-custom-auth
42
-
app_name (default is "djpackage")? custom_auth
43
-
project_short_description (default is "Your project description goes here")?
44
-
year (default is "2014")?
45
-
version (default is "0.1.0")?
46
-
47
-
#### Getting it onto GitHub
48
-
49
-
To put your project up on GitHub, you'll need a repository for it to live in. You can create a new repository [here][new-repo]. If you need help, check out the [Create A Repo][create-a-repo] article on GitHub.
50
-
51
-
52
-
#### Adding to Travis CI
53
-
54
-
We recommend using [Travis CI][travis-ci], a hosted continuous integration service which integrates well with GitHub and is free for public repositories.
55
-
56
-
To get started with Travis CI, [sign in][travis-ci] with your GitHub account. Once you're signed in, go to your [profile page][travis-profile] and enable the service hook for the repository you want.
57
-
58
-
If you use the cookiecutter template, your project will already contain a `.travis.yml` file which Travis CI will use to build your project and run tests. By default, builds are triggered every time you push to your repository or create Pull Request.
59
-
60
-
#### Uploading to PyPI
61
-
62
-
Once you've got at least a prototype working and tests running, you should publish it on PyPI to allow others to install it via `pip`.
63
-
64
-
You must [register][pypi-register] an account before publishing to PyPI.
65
-
66
-
To register your package on PyPI run the following command.
67
-
68
-
$ python setup.py register
69
-
70
-
If this is the first time publishing to PyPI, you'll be prompted to login.
71
-
72
-
Note: Before publishing you'll need to make sure you have the latest pip that supports `wheel` as well as install the `wheel` package.
73
-
74
-
$ pip install --upgrade pip
75
-
$ pip install wheel
76
-
77
-
After this, every time you want to release a new version on PyPI just run the following command.
78
-
79
-
$ python setup.py publish
80
-
You probably want to also tag the version now:
81
-
git tag -a {0} -m 'version 0.1.0'
82
-
git push --tags
83
-
84
-
After releasing a new version to PyPI, it's always a good idea to tag the version and make available as a GitHub Release.
85
-
86
-
We recommend to follow [Semantic Versioning][semver] for your package's versions.
87
-
88
-
### Development
89
-
90
-
#### Version requirements
91
-
92
-
The cookiecutter template assumes a set of supported versions will be provided for Python and Django. Make sure you correctly update your requirements, docs, `tox.ini`, `.travis.yml`, and `setup.py` to match the set of versions you wish to support.
93
-
94
-
#### Tests
95
-
96
-
The cookiecutter template includes a `runtests.py` which uses the `pytest` package as a test runner.
97
-
98
-
Before running, you'll need to install a couple test requirements.
99
-
100
-
$ pip install -r requirements.txt
101
-
102
-
Once requirements installed, you can run `runtests.py`.
103
-
104
-
$ ./runtests.py
105
-
106
-
Run using a more concise output style.
107
-
108
-
$ ./runtests.py -q
109
-
110
-
Run the tests using a more concise output style, no coverage, no flake8.
111
-
112
-
$ ./runtests.py --fast
113
-
114
-
Don't run the flake8 code linting.
115
-
116
-
$ ./runtests.py --nolint
117
-
118
-
Only run the flake8 code linting, don't run the tests.
119
-
120
-
$ ./runtests.py --lintonly
121
-
122
-
Run the tests for a given test case.
123
-
124
-
$ ./runtests.py MyTestCase
125
-
126
-
Run the tests for a given test method.
127
-
128
-
$ ./runtests.py MyTestCase.test_this_method
129
-
130
-
Shorter form to run the tests for a given test method.
131
-
132
-
$ ./runtests.py test_this_method
133
-
134
-
To run your tests against multiple versions of Python as different versions of requirements such as Django we recommend using `tox`. [Tox][tox-docs] is a generic virtualenv management and test command line tool.
135
-
136
-
First, install `tox` globally.
137
-
138
-
$ pip install tox
139
-
140
-
To run `tox`, just simply run:
141
-
142
-
$ tox
143
-
144
-
To run a particular `tox` environment:
145
-
146
-
$ tox -e envlist
147
-
148
-
`envlist` is a comma-separated value to that specifies the environments to run tests against. To view a list of all possible test environments, run:
149
-
150
-
$ tox -l
151
-
152
-
#### Version compatibility
19
+
### Version compatibility
153
20
154
21
Sometimes, in order to ensure your code works on various different versions of Django, Python or third party libraries, you'll need to run slightly different code depending on the environment. Any code that branches in this way should be isolated into a `compat.py` module, and should provide a single common interface that the rest of the codebase can use.
0 commit comments