Language and Toolkit
Python
Nicotine+ is a Python application originally based on backend code from the PySoulSeek project started in 2001. The project uses only Python in the codebase, allowing Nicotine+ to run on almost any system without compilation.The project aims to support the oldest Python version still receiving security updates, up to the latest. Currently, Python 3.9+ is required.
GTK Toolkit
Nicotine+ uses GTK as its GUI toolkit, a decision that dates back to the original Nicotine project. The switch from wxPython (used by PySoulSeek) was made due to various issues at the time, such as large memory overhead and long compile/build times.GTK fits the project’s needs, and there are no plans of switching to another toolkit. Both GTK 3 (>= 3.24.24) and GTK 4 (>= 4.6.9) are supported.
Design Philosophy
Keep It Simple
Many applications fall into the trap of adding endless options without thinking about the bigger picture. Nicotine+ is feature-rich, but attempts to provide well-designed, well-integrated features that work out of the box. The same principle applies when writing code:- Try to simplify code as much as possible
- Avoid overengineering
- Write code that is maintainable and readable by humans
Dependency Management
Nicotine+ aims to be as portable as possible, providing access to the Soulseek network for people who cannot run the official Soulseek client. The application runs on almost any architecture and system available. When considering dependencies:- Prefer Python Standard Library - Use modules included in the standard library whenever possible
- Avoid “convenient” dependencies - If the standard library includes the required functionality, use it
- Prefer pure-Python dependencies - These are easier to install and more likely to work on less common systems
- Consider bundling - Small, self-contained dependencies can be bundled with proper attribution (but not security-critical or rapidly changing dependencies)
Performance
Profiling code changes is important to ensure that Nicotine+ performs well and uses fewer system resources. The goal is to develop a lightweight client that runs well on older hardware and small servers.Performance Best Practices
Due to Python’s interpreted nature, addressing performance issues can be a challenge. These points generally help:Use efficient data structures
Use dictionaries and sets for faster membership checks (O(1)) compared to lists (O(n))
Leverage the standard library
Parts of the standard library are written in C and perform better than pure-Python counterparts, especially in hot code paths
Profiling with py-spy
py-spy is an excellent tool for profiling in real time:- Press
Lto aggregate by line number - Press
Rto reset the view
Debug Logging
Verbose logging can be enabled to ease debugging. The following log categories are available:- Connections - Logging related to networking (
slskproto.py) - Messages - Incoming and outgoing protocol messages (
slskmessages.py) - Transfers - Logging related to file transfers (
transfers.py) - Miscellaneous - General debug log messages
Enabling Debug Logging
Show the log pane
Click the ellipsis icon in the bottom right corner of the main window to show the log pane
Enable log categories
Right-click the log pane to show the context menu. Enable the log categories you need in the
Log Categories submenuSoulseek Protocol
The Soulseek network uses its own protocol for interoperability between clients. The protocol is proprietary, and no official documentation is available. Nicotine+‘s protocol implementation is developed by observing the behavior of the official Soulseek NS and SoulseekQt clients. The team maintains unofficial documentation inSLSKPROTOCOL.md.
Getting Started
Ready to contribute? Continue to the next sections:- Setup - Set up your development environment
- Architecture - Understand the project structure
- Testing - Run tests and validate your changes