It is highly recommended that you use Visual Studio Code (VS Code) for this project. All instructions below will assume that you are using this editor. If you prefer to use a different editor, that is acceptable, but it may be more difficult to get help when getting started.

To install VS Code:

1. Go to https://code.visualstudio.com/download and download the installer for your operating system.
2. Run the installer and follow the setup instructions.

VS Code Extensions:

Extensions are small add-ons that enhance VS Code's functionality. Make sure you install the following extensions:

• Better Comments (by Aaron Bond)
• Python Extension Pack (by Don Jayamanne)
• Error Lens (by Alexander)
• GitLens (by GitKraken)
• Path Intellisense (by Christian Kohler)
• Black Formatter (by Microsoft)

Ensure that you have Python 3.12 installed on your system by running the following command:

python3 --version

This command will display the version of Python 3 that is installed, such as Python 3.12.10.

If you are using Windows, or if the python3 command does not work (common on Windows), try:

python --version

This command will display the version of Python that the python command points to.

If Python is not installed, or you need a different version, follow the installation instructions for your operating system from the official Python documentation: https://www.python.org/downloads/.
NOTE: We are package locked to python 3.12 so you may encounter issues with newer versions. It does not matter whether you use Python 3.12.9, 3.12.10, or any other 3.12.x version.

⚠️ Read through this entire section for project setup before you start applying the instructions in your editor. This is necessary to avoid mistakes!

You'll need to clone the repository containing the project. To set it up:

1. Open VS Code (or your preferred editor, but all following instructions will be in terms of VS Code)
2. Go to: File → Open Folder. Choose or create a folder for your repository.
3. Open a terminal: Terminal → New Terminal
4. In the terminal, run the following commands:

# Method 1
git init
git remote add origin https://github.com/CApy-RPI/onboarding
git pull origin main

This will initialize a Git repository in your folder, connect it to the onboarding project, and download all materials from onboarding.

Alternatively, you can use the following commands:

# Method 2
git clone https://github.com/CApy-RPI/onboarding
cd onboarding

The git clone command essentially does everything the above 3 commands do, just in one step. The cd command is necessary to change the directory.

⚠️ Important: Do not do both methods. If you use git clone, it already sets up everything. You do not need to run git init, git remote add origin, or git pull. The same applies the other way around.

Why? Running both methods will cause Git errors or duplicate files. Thus, avoid doing so!

In the future, if you need to open a new directory and download materials for a different project, you will use one of the two methods, but replace the link. For example:

# First method
git init
git remote add origin https://github.com/CApy-RPI/other-project
git pull origin main

# Second method
git clone https://github.com/CApy-RPI/other-project
cd other-project

In CApy, we will use a Virtual Environment - A tool that helps keep Python packages for each project separate. Using a virtual environment helps prevent conflicts when projects require different versions of the same package.

A virtual environment creates a local folder that has its own copy of the Python interpreter and its own place to install packages. This ensures that packages for one project do not affect others.

If you are on Windows, it is strongly recommended to use Command Prompt (cmd), since it works most reliably with .venv and Python.

Use the following commands to create and activate the virtual environment:

# Create the virtual environment
python -m venv .venv

# Activate it on Windows
.venv\Scripts\activate

# Activate it on Unix/MacOS
source .venv/bin/activate

If you successfully created and activated the virtual environment, you should see (.venv) at the beginning of your terminal prompt (in VS Code). This indicates that your virtual environment is active and ready to use.

🔍 To double check:

• On Windows: Run where python
• On Mac/Linux: Run which python

The result should point to .venv\Scripts\python.exe on Windows, or .venv/bin/python on Mac/Linux.

The pip command is the standard package installer for Python. With this, you can download, install, and manage packages from the Python Package Index.

• With the pip install command, you download the package and any other packages it depends on, and install them into your current environment.

Use requirements.txt for production dependencies and requirements_dev.txt for development dependencies:

# Install production dependencies
pip install -r requirements.txt

# Install development dependencies
pip install -r requirements_dev.txt

• requirements.txt: Contains the dependencies required for the application to run in production.
• requirements_dev.txt: Contains additional dependencies required for development, such as testing and linting tools.

Example requirements.txt:

discord.py      # For building Discord bots & interacting with the Discord API
pymongo         # Stores data that is easy to read & work with in code

Example requirements_dev.txt:

pytest       # For writing & running tests
flake8       # For checking code style & linting
black        # For formatting code
mypy         # Checks if type annotations are correct

• Use a .env file to hold all sensitive access tokens.
• Ask your project lead for access to these tokens.
• The .env file must be located in the directory from which you run the bot.

⚠️ Important: Do not share any of the contents in your .env file. Doing so could put the security of your project at risk. Always keep this file private and ensure it is not committed to version control (GitHub).

Method 1:

.venv\Scripts\activate
python src/capy_app/main.py

If using the above to run the bot: .env must be in src/

Method 2:

1. Assuming you are using VS Code, at the top left select Run → Add Configuration... → Python Debugger → Python File.

2. At this point, you should have a launch.json file open. Change the program: field to "src/capy_app/main.py".

3. Now, you should be all set to run. In the top left again, go to Run → Start Debugging.

It is necessary to create your own bot, separate from the CAPY DEV bot, to use for testing.

The CAPY DEV bot is a shared resource. If too many people run the bot at the same time, it can lead to resource limitations and performance problems.

Thus, by creating your own bot, you can test your code freely and experiment without disrupting others.

Steps to Create Your Own Bot:

1. Go to https://discord.com/developers/applications.
2. In the top right, select New Application. Give it a name. Click Create.
3. On the left, you should see a Bot tab. Under that tab, you can customize your bot:

   • For the USERNAME, name it CAPY-your_name, with your first name.

   • Under Privledged Gateway Intents, check the Presence Intent, Server Members Intent, and Message Content Intent.

     

   • Under Bot Permissions, check Administrator.

4. Under the USERNAME field you previously filled out, you should see a Reset Token button. Click it and copy the token provided. Do not share this token or commit it to GitHub.
   • In VS Code, navigate to your .env file. At the top, you should see a BOT_TOKEN=[token] already. Paste your token there. Save the file.
5. On the left, you should see an OAuth2 tab. Under that tab, navigate to OAuth2 URL Generator.
   • Under SCOPES, select bot.
   • Under BOT PERMISSIONS, select Administrator.
   • Ensure the INTEGRATION TYPE is Guild Install.
   • Copy the generated URL and send it to your team lead. They will add your bot to the CApy server.

And there you have it! Once your bot is added to the server, you will be able to test your code freely and safely. Happy coding!