As a prerequisite to working on Pythondotorg, Docker, Docker Compose andmake will need to be installed locally.
Note
Docker Compose will be installed byDocker Mac andDocker for Windows automatically.
make is a build automation tool that automatically builds executebale programs and libraries from source code by reading files called Makefiles. Themake utility comes defaulted with most unix distributions.
To get the Pythondotorg source code,fork the repository onGitHub andclone it to your local machine:
gitclonegit@github.com:YOUR-USERNAME/pythondotorg.git
Add aremote andsync regularly to stay current with the repository.
gitremoteaddupstreamhttps://github.com/python/pythondotorggitcheckoutmaingitfetchupstreamgitmergeupstream/main
InstallDocker Engine
Note
The best experience for building Pythondotorg on Windows is to use theWindows Subsystem for Linux(WSL) in combination with bothDocker for Windows andDocker for Linux.
Verify that the Docker installation is successful by running:docker-v
Once you have Docker and Docker Compose installed, run:
makeserve
This will pull down all the required docker containers, build the environment for pythondotorg, run migrations, load development fixtures, and start all of the necessary services.
Once complete, you will see the following in your terminal output:
web_1|Startingdevelopmentserverathttp://0.0.0.0:8000/web_1|QuittheserverwithCONTROL-C.
You can view these results in your local web browser at:http://localhost:8000
To reset your local environment, run:
makeclean
To apply migrations, run:
makemigrate
To generate new migrations, run:
makemigrations
You can also run arbitrary Django management commands via:
makemanage<NAME_OF_COMMAND>
This is a simple wrapper around runningpythonmanage.py in the container, all arguments passed tomakemanage will be passed through.
First, installPostgreSQL on your machine and run it.pythondotorg currently uses Postgres 15.x.
Then clone the repository:
$ git clone git://github.com/python/pythondotorg.git
Then create a virtual environment:
$ python3 -m venv venv
And then you’ll need to install dependencies. You don’t need to usepip3 inside a Python 3 virtual environment:
$ pip install -r dev-requirements.txt
pythondotorg will look for a PostgreSQL database namedpythondotorg by default. Run the following command to create a new database:
$ createdb pythondotorg -E utf-8 -l en_US.UTF-8
Note
If the above command fails to create a database and you see an error message similar to:
createdb:databasecreationfailed:ERROR:permissiondeniedtocreatedatabase
Use the following command to create a database withpostgres user as the owner:
$ sudo -u postgres createdb pythondotorg -E utf-8 -l en_US.UTF-8
Note that this solution may not work if you’ve installed PostgreSQL via Homebrew.
If you get an error like this:
createdb:databasecreationfailed:ERROR:newcollation(en_US.UTF-8)isincompatiblewiththecollationofthetemplatedatabase(en_GB.UTF-8)
Then you will have to change the value of the-l option to what your database was set up with initially.
To change database configuration, you can add the following setting topydotorg/settings/local.py (or you can use theDATABASE_URL environment variable):
DATABASES={'default':dj_database_url.parse('postgres:///your_database_name'),}
If you prefer to use a simpler setup for your database you can use SQLite. Set theDATABASE_URL environment variable for the current terminal session:
$ export DATABASE_URL="sqlite:///pythondotorg.db"
Note
If you prefer to set this variable in a more permanent way add the above line in your.bashrc file. Then it will be set for all terminal sessions in your system.
Whichever database type you chose, now it’s time to run migrations:
$ ./manage.py migrate
To compile and compress static media, you will needcompass andyui-compressor:
$ gem install bundler$ bundle install
Note
To installyui-compressor, use your OS’s package manager or download it directly then add the executable to yourPATH.
To create initial data for the most used applications, run:
$ ./manage.py create_initial_data
Seepythondotorgcreate_initial_data for the command options to specify while creating initial data.
Finally, start the development server:
$ ./manage.py runserver
The search feature in Python.org uses Elasticsearch engine. If you want to test out this feature, you will need to installElasticsearch.
Once you have it installed, update the URL value ofHAYSTACK_CONNECTIONS settings inpydotorg/settings/local.py to your local ElasticSearch server.
Warning
When editing frontend styles, ensure you ONLY edit the.scss files.
These will then be compiled into.css files automatically.
Static files are automatically compiled inside theDocker Composestatic containerwhen runningmakeserve.
When your pull request has stylesheet changes, commit the.scss files and the compiled.css files.Otherwise, ignore committing and pushing the.css files.
To run the test suite:
$ ./manage.py test
To generate coverage report:
$ coverage run manage.py test$ coverage report
Generate an HTML report withcoveragehtml if you like.
Create a super user (for a new DB):
$ ./manage.py createsuperuser
Want to save some data from your DB before nuking it, and then load it back in?:
$ ./manage.py dumpdata --format=json --indent=4 $APPNAME > fixtures/$APPNAME.json