Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
18 changes: 9 additions & 9 deletions README.md
Original file line number Diff line number Diff line change
@@ -1,20 +1,20 @@
# Python Tutorials

A free Python course in **English** and **Uzbek**, from your first `print()` to decorators and async. Examples run in the browser, exercises are checked on the page, and nothing needs to be installed.
A Python course in **English** and **Uzbek**, from your first `print()` to decorators and async. Examples run in the browser, exercises are checked on the page, and nothing needs to be installed.

**Live site:** [yakhyo.github.io/python-tutorials](https://yakhyo.github.io/python-tutorials/) · [Uzbek version](https://yakhyo.github.io/python-tutorials/uz/)
**Live site:** [yakhyo.github.io/python-tutorials](https://yakhyo.github.io/python-tutorials/) (opens in Uzbek) · [English version](https://yakhyo.github.io/python-tutorials/en/)

> Pythonni noldan örganmoqçimisiz? Kurs toʻliq özbek tilida ham bor: [özbekça versiya](https://yakhyo.github.io/python-tutorials/uz/).
> Pythonni noldan örganmoqçimisiz? Kurs töliq özbek tilida ham bor: [özbekça versiya](https://yakhyo.github.io/python-tutorials/uz/).

## What's inside

82 lessons in 14 modules, written for Python 3.14. Every lesson has runnable examples, common mistakes with real error output, and five exercises with solutions. Every module ends with a quiz.
82 lessons in 14 modules, written for Python 3.14. Every lesson has runnable examples, common mistakes with real error output, and five practice tasks: exercises with solutions in the concept lessons, challenges with hints in the seven projects. Every module ends with a quiz.

| Part | Modules |
| --- | --- |
| **Foundations** | [Getting Started](docs/lessons/01-getting-started) · [Values and Variables](docs/lessons/02-values-and-variables) · [Decisions](docs/lessons/03-making-decisions) · [Loops](docs/lessons/04-loops) · [Collections](docs/lessons/05-collections) · [Functions](docs/lessons/06-functions) |
| **Real Programs** | [Standard Library](docs/lessons/07-modules-and-the-standard-library) · [Errors and Files](docs/lessons/08-errors-and-files) · [Classes](docs/lessons/09-classes-and-objects) · [Object-Oriented Design](docs/lessons/10-object-oriented-design) · [Testing](docs/lessons/11-testing-and-debugging) · [Generators and Regex](docs/lessons/12-going-further) · [Data with pandas](docs/lessons/13-working-with-data) *(optional)* |
| **Advanced** *(optional)* | [Decorators, the data model, context managers, async, performance, design patterns and concurrency](docs/lessons/14-advanced-python) |
| **Foundations** | [Getting Started](docs/en/lessons/01-getting-started) · [Values and Variables](docs/en/lessons/02-values-and-variables) · [Decisions](docs/en/lessons/03-making-decisions) · [Loops](docs/en/lessons/04-loops) · [Collections](docs/en/lessons/05-collections) · [Functions](docs/en/lessons/06-functions) |
| **Real Programs** | [Standard Library](docs/en/lessons/07-modules-and-the-standard-library) · [Errors and Files](docs/en/lessons/08-errors-and-files) · [Classes](docs/en/lessons/09-classes-and-objects) · [Object-Oriented Design](docs/en/lessons/10-object-oriented-design) · [Testing](docs/en/lessons/11-testing-and-debugging) · [Generators and Regex](docs/en/lessons/12-going-further) · [Data with pandas](docs/en/lessons/13-working-with-data) *(optional)* |
| **Advanced** *(optional)* | [Decorators, the data model, context managers, async, performance, design patterns and concurrency](docs/en/lessons/14-advanced-python) |

Seven guided projects along the way: a number guessing game, quiz game, expense tracker, library system, text analyzer, sales report and log pipeline.

Expand All @@ -41,11 +41,11 @@ python3 scripts/lint.py # check lessons against the template

## Contributing lessons

Add the lesson to `docs/.vitepress/course.json`, then run `python3 scripts/organize-lessons.py` to place the file. Use `docs/lessons/05-collections/04-dictionaries.md` as the reference lesson, and mirror every change in the Uzbek lesson under `docs/uz/darslar/`.
Add the lesson to `docs/.vitepress/course.json`, and its Uzbek title and group to `docs/.vitepress/course-uz.json` with the same slug and at the same position, then run `python3 scripts/organize-lessons.py` to place the file. Use `docs/en/lessons/05-collections/04-dictionaries.md` as the reference lesson, and mirror every change in the Uzbek lesson under `docs/uz/lessons/`.

## Deployment

Work happens on `dev`. CI runs on pull requests into `dev`. Deploys and releases to GitHub Pages run manually from the Actions tab.
Work happens on `dev`. CI runs on every push to `dev` and on pull requests into `main`. Deploys and releases to GitHub Pages run manually from the Actions tab.

## License

Expand Down
149 changes: 99 additions & 50 deletions docs/.vitepress/config.mjs
Original file line number Diff line number Diff line change
@@ -1,4 +1,5 @@
import { defineConfig } from 'vitepress'
import { createLogger } from 'vite'
import { readFileSync, existsSync } from 'node:fs'
import catppuccinLatte from '@shikijs/themes/catppuccin-latte'
import catppuccinMocha from '@shikijs/themes/catppuccin-mocha'
Expand Down Expand Up @@ -52,8 +53,8 @@ const load = file => JSON.parse(readFileSync(new URL(file, import.meta.url)))
const groupsOf = list => [...new Set(list.map(lesson => lesson.group))]

// Lesson files live in numbered module folders so they sort in course order,
// e.g. lessons/06-functions/01-defining-functions.md. `rewrites` below keeps the
// URLs short (/lessons/defining-functions). scripts/organize-lessons.py moves the files.
// e.g. en/lessons/06-functions/01-defining-functions.md. `rewrites` below keeps the
// URLs short (/en/lessons/defining-functions). scripts/organize-lessons.py moves the files.
const moduleFolder = group => {
const [number, name] = group.split(' · ')
return `${number}-${name.replace(/\(.*?\)/g, '').toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-|-$/g, '')}`
Expand All @@ -67,40 +68,51 @@ const lessonFiles = list => {
}))
}

// English (root locale).
// The sidebar has three sections of equal weight: the 12-module course, and the two follow-on
// tracks (modules 13 and 14). Each track has a landing page (en/data.md, en/advanced.md) and is
// named without the module number or the "(Optional)" suffix that course.json keeps for
// scripts/make-notebooks.py. Section and module headings are styled in theme/style.css.
const tracks = { '13': 'data', '14': 'advanced' }
const sidebarFor = ({ course, lang, start, quizLabel, hasQuiz, overview, core }) => {
const modules = groupsOf(course).map(text => {
const number = text.slice(0, 2)
const items = course.filter(l => l.group === text).map(l => ({ text: l.title, link: `/${lang}/lessons/${l.slug}` }))
if (hasQuiz(number)) items.push({ text: `<span class="checkpoint-link">${quizLabel}</span>`, link: `/${lang}/checkpoints/module-${number}` })
const track = tracks[number]
if (!track) return { number, text, collapsed: number !== '01', items }
const name = text.split(' · ')[1].replace(/\s*\(.*?\)$/, '')
return { number, text: name, collapsed: true, items: [{ text: overview, link: `/${lang}/${track}` }, ...items] }
})
const group = ({ number, ...item }) => item
return [
start,
{ text: core, items: modules.filter(m => !tracks[m.number]).map(group) },
...modules.filter(m => tracks[m.number]).map(group)
]
}

// English (served under /en/).
const courseEn = load('./course.json')
const files = lessonFiles(courseEn)
const hasQuiz = number => existsSync(new URL(`./quizzes/module-${number}.json`, import.meta.url))
const sidebarEn = [
{ text: 'Start Here', items: [{ text: 'Course Overview', link: '/' }, { text: 'Playground', link: '/playground' }, { text: 'Python Lab (notebooks)', link: '/lab' }] },
...groupsOf(courseEn).map(text => {
const lessons = courseEn.filter(l => l.group === text)
const number = text.slice(0, 2)
const items = lessons.map(l => ({ text: l.title, link: `/lessons/${l.slug}` }))
if (hasQuiz(number)) items.push({ text: '<span class="checkpoint-link">Checkpoint quiz</span>', link: `/checkpoints/module-${number}` })
return { text, collapsed: number !== '01', items }
})
]
const sidebarEn = sidebarFor({
course: courseEn, lang: 'en', hasQuiz, quizLabel: 'Checkpoint quiz', overview: 'Track overview', core: 'Python',
start: { text: 'Start Here', items: [{ text: 'Course Overview', link: '/en/' }, { text: 'Playground', link: '/en/playground' }, { text: 'Python Lab', link: '/en/lab' }] }
})

// Uzbek (/uz/ locale): the same course, translated. Titles come from course-uz.json.
// Uzbek (the default language, served under /uz/): the same course, translated. Titles come from course-uz.json.
const courseUz = load('./course-uz.json')
const hasQuizUz = number => existsSync(new URL(`../uz/nazorat/module-${number}.md`, import.meta.url))
const sidebarUz = [
{ text: 'Boşlaş', items: [{ text: 'Darslik haqida', link: '/uz/' }, { text: 'Sinov maydonçasi', link: '/uz/sinov-maydoni' }, { text: 'Python laboratoriyasi', link: '/uz/laboratoriya' }] },
...groupsOf(courseUz).map(text => {
const lessons = courseUz.filter(l => l.group === text)
const number = text.slice(0, 2)
const items = lessons.map(l => ({ text: l.title, link: `/uz/darslar/${l.slug}` }))
if (hasQuizUz(number)) items.push({ text: '<span class="checkpoint-link">Nazorat testi</span>', link: `/uz/nazorat/module-${number}` })
return { text, collapsed: number !== '01', items }
})
]
const hasQuizUz = number => existsSync(new URL(`../uz/checkpoints/module-${number}.md`, import.meta.url))
const sidebarUz = sidebarFor({
course: courseUz, lang: 'uz', hasQuiz: hasQuizUz, quizLabel: 'Nazorat testi', overview: 'Yönaliş haqida', core: 'Python',
start: { text: 'Boşlaş', items: [{ text: 'Darslik haqida', link: '/uz/' }, { text: 'Sinov maydonçasi', link: '/uz/playground' }, { text: 'Python laboratoriyasi', link: '/uz/lab' }] }
})

// Markdown plugin: an italic lesson title (for example *Nested Data* or *Içma-iç maʼlumotlar*)
// becomes a link to that lesson, so lessons can reference each other without hard-coded links.
const linkSets = [
{ test: path => path.startsWith('lessons/') || path.startsWith('checkpoints/') || path === 'index.md', prefix: '/lessons/', dir: 'lessons/', titles: new Map(courseEn.map(l => [l.title, `/lessons/${l.slug}`])) },
{ test: path => path.startsWith('uz/'), prefix: '/uz/darslar/', dir: 'uz/darslar/', titles: new Map(courseUz.map(l => [l.title, `/uz/darslar/${l.slug}`])) }
{ test: path => path.startsWith('en/'), prefix: '/en/lessons/', dir: 'en/lessons/', titles: new Map(courseEn.map(l => [l.title, `/en/lessons/${l.slug}`])) },
{ test: path => path.startsWith('uz/'), prefix: '/uz/lessons/', dir: 'uz/lessons/', titles: new Map(courseUz.map(l => [l.title, `/uz/lessons/${l.slug}`])) }
]
function linkLessonTitles(md) {
md.core.ruler.push('lesson_title_links', state => {
Expand All @@ -127,61 +139,98 @@ function linkLessonTitles(md) {
})
}

// Markdown plugin: ```flow, ```tree and ```anatomy blocks become drawn diagrams. Each component
// in theme/ explains its own format. The text is URL-encoded so that it travels safely through
// an HTML attribute.
const DIAGRAMS = { flow: 'FlowDiagram', tree: 'TreeDiagram', anatomy: 'CodeAnatomy' }
function flowDiagrams(md) {
const fence = md.renderer.rules.fence
md.renderer.rules.fence = (tokens, index, options, env, self) => {
const token = tokens[index]
const component = DIAGRAMS[token.info.trim()]
if (!component) return fence(tokens, index, options, env, self)
return `<${component} source="${encodeURIComponent(token.content).replace(/'/g, '%27')}" />\n`
}
}

const base = process.env.SITE_BASE || '/'

const rewrites = Object.fromEntries(Object.entries(files).flatMap(([slug, file]) => [
[`lessons/${file}`, `lessons/${slug}.md`],
[`uz/darslar/${file}`, `uz/darslar/${slug}.md`]
[`en/lessons/${file}`, `en/lessons/${slug}.md`],
[`uz/lessons/${file}`, `uz/lessons/${slug}.md`]
]))

// VitePress 1.x is written for Vite 5; this project runs it on Vite 6, which prints a warning
// about one line in VitePress's own search box ("Failed to resolve /@localSearchIndex") every time
// the dev server starts. Search works either way, so that one message is dropped. Every other
// warning still gets through.
const logger = createLogger()
const warn = logger.warn
logger.warn = (message, options) => { if (!String(message).includes('/@localSearchIndex')) warn(message, options) }

export default defineConfig({
title: 'python.uz',
vite: { customLogger: logger },
title: 'codeuz',
base, outDir: '../dist',
sitemap: { hostname: 'https://yakhyo.github.io/python-tutorials/' },
lastUpdated: true,
rewrites,
// Catppuccin Latte/Mocha, contrast-corrected above; the CodeMirror editor matches (--cm-* in theme/style.css).
markdown: { theme: codeThemes, config: md => linkLessonTitles(md) },
markdown: { theme: codeThemes, config: md => { linkLessonTitles(md); flowDiagrams(md) } },
// The Python Lab (JupyterLite) is built separately into dist/lab by scripts/build-lab.sh.
ignoreDeadLinks: [/^\/lab\//],
head: [
['link', { rel: 'icon', href: `${base}favicon.svg` }],
// Both languages live under a prefix (/uz/, /en/). Uzbek is the default: the bare site
// root sends every visitor to /uz/, and the language menu switches to English.
['script', {}, `(function () { var base = ${JSON.stringify(base)}; var path = location.pathname; if (path !== base && path !== base + 'index.html') return; location.replace(base + 'uz/' + location.search + location.hash) })()`],
['link', { rel: 'preconnect', href: 'https://fonts.googleapis.com' }],
['link', { rel: 'preconnect', href: 'https://fonts.gstatic.com', crossorigin: '' }],
['link', { rel: 'stylesheet', href: 'https://fonts.googleapis.com/css2?family=Inter:wght@400;600;700;800&display=swap' }]
],
// `root` is the fallback locale: it also covers the site root and the 404 page, so it is Uzbek.
locales: {
root: {
label: 'English', lang: 'en',
description: 'Learn Python from scratch with clear explanations, runnable examples, and exercises.',
themeConfig: {
nav: [{ text: 'Lessons', link: `/lessons/${courseEn[0].slug}` }, { text: 'Playground', link: '/playground' }, { text: 'Lab', link: '/lab' }],
sidebar: sidebarEn,
outline: { label: 'On this page', level: [2, 3] },
docFooter: { prev: 'Previous lesson', next: 'Next lesson' },
editLink: { pattern: 'https://github.com/yakhyo/python-tutorials/edit/dev/docs/:path', text: 'Suggest a change to this lesson' },
lastUpdatedText: 'Last updated'
}
},
uz: {
label: 'Özbekça', lang: 'uz', link: '/uz/',
description: 'Pythonni noldan örganing: tuşunarli izohlar, brauzerda işlaydigan misollar va maşqlar.',
themeConfig: {
nav: [{ text: 'Darslar', link: '/uz/darslar/what-is-python' }, { text: 'Sinov maydonçasi', link: '/uz/sinov-maydoni' }, { text: 'Laboratoriya', link: '/uz/laboratoriya' }],
nav: [{ text: 'Darslar', link: `/uz/lessons/${courseUz[0].slug}` }, { text: 'Sinov maydonçasi', link: '/uz/playground' }, { text: 'Laboratoriya', link: '/uz/lab' }],
sidebar: sidebarUz,
outline: { label: 'Bu sahifada', level: [2, 3] },
docFooter: { prev: 'Oldingi dars', next: 'Keyingi dars' },
darkModeSwitchLabel: 'Rang rejimi', sidebarMenuLabel: 'Mundarija', returnToTopLabel: 'Yuqoriga', langMenuLabel: 'Tilni özgartiriş',
editLink: { pattern: 'https://github.com/yakhyo/python-tutorials/edit/dev/docs/:path', text: 'Bu darsga özgartiriş taklif qiliş' },
editLink: { pattern: 'https://github.com/yakhyo/python-tutorials/edit/dev/docs/:path', text: 'Bu sahifaga özgartiriş taklif qiliş' },
lastUpdatedText: 'Oxirgi yangilanish', notFound: { title: 'Sahifa topilmadi', quote: 'Bu manzilda sahifa yöq. Balki u köçirilgandir.', linkText: 'Boş sahifaga' }
}
},
en: {
label: 'English', lang: 'en', link: '/en/',
description: 'Learn Python from scratch with clear explanations, runnable examples, and exercises.',
themeConfig: {
nav: [{ text: 'Lessons', link: `/en/lessons/${courseEn[0].slug}` }, { text: 'Playground', link: '/en/playground' }, { text: 'Lab', link: '/en/lab' }],
sidebar: sidebarEn,
outline: { label: 'On this page', level: [2, 3] },
docFooter: { prev: 'Previous lesson', next: 'Next lesson' },
editLink: { pattern: 'https://github.com/yakhyo/python-tutorials/edit/dev/docs/:path', text: 'Suggest a change to this page' },
lastUpdatedText: 'Last updated'
}
}
},
themeConfig: {
// The official Python logo (unaltered, from python.org/community/logos) next to the site name.
logo: { src: '/python-logo.svg', alt: 'Python' },
siteTitle: false,
socialLinks: [{ icon: 'github', link: 'https://github.com/yakhyo/python-tutorials', ariaLabel: 'GitHub' }],
search: { provider: 'local', options: { locales: { uz: { translations: { button: { buttonText: 'Qidiriş', buttonAriaLabel: 'Darslardan qidiriş' }, modal: { noResultsText: 'Natija topilmadi', resetButtonTitle: 'Tozalaş', footer: { selectText: 'tanlaş', navigateText: 'ötiş', closeText: 'yopiş' } } } } } } }
// The site carries the name of the author's YouTube channel, codeuz. Its mark is the Python
// prompt ">>>" and a cursor (public/logo.svg, with a lighter version for dark mode). The name
// next to it is text, with "uz" in the accent color.
logo: { light: '/logo.svg', dark: '/logo-dark.svg', alt: '' },
siteTitle: 'code<span class="site-tld">uz</span>',
socialLinks: [{ icon: 'youtube', link: 'https://youtube.com/codeuz', ariaLabel: 'YouTube' }, { icon: 'github', link: 'https://github.com/yakhyo/python-tutorials', ariaLabel: 'GitHub' }],
// Search matches both Uzbek Latin spellings. The lessons use ş, ç, ö, ğ, but many people type
// sh, ch, o', g'. Every word, in the index and in what the visitor types, is reduced to one
// plain form ("özgaruvçi", "o'zgaruvchi" and "ozgaruvchi" all become "ozgaruvchi").
// VitePress copies these two functions to the browser as text, so they must not use anything
// defined outside themselves.
search: { provider: 'local', options: { miniSearch: { options: {
tokenize: text => text.replace(/(\p{L})['’‘`ʻʼ](?=\p{L})/gu, '$1').split(/[\n\r\p{Z}\p{P}]+/u),
processTerm: term => term.toLowerCase().replace(/ş/g, 'sh').replace(/ç/g, 'ch').replace(/ö/g, 'o').replace(/ğ/g, 'g').replace(/[ʻʼ]/g, '')
} }, locales: { root: { translations: { button: { buttonText: 'Qidiriş', buttonAriaLabel: 'Darslardan qidiriş' }, modal: { noResultsText: 'Natija topilmadi', resetButtonTitle: 'Tozalaş', footer: { selectText: 'tanlaş', navigateText: 'ötiş', closeText: 'yopiş' } } } } } } }
}
})
2 changes: 1 addition & 1 deletion docs/.vitepress/quizzes/module-03.json
Original file line number Diff line number Diff line change
Expand Up @@ -116,7 +116,7 @@
"SyntaxError"
],
"answer": 0,
"explanation": "A bare name in a case pattern is a capture pattern: it matches any value and binds it, so the last case always runs when nothing before it matched. That is why it must come last.",
"explanation": "A plain name in a case pattern captures the value: it matches anything and stores the value in that name, so this case runs whenever nothing before it matched. That is why it must come last.",
"lesson": "match-statement"
},
{
Expand Down
Loading
Loading