diff --git a/.gitignore b/.gitignore index 90a4c0015..e8404512b 100644 --- a/.gitignore +++ b/.gitignore @@ -158,3 +158,12 @@ cython_debug/ #.DS_Store .DS_Store + +# Next.js frontend (web/) — the Python `lib/` rule above would otherwise +# swallow web/src/lib, so explicitly un-ignore it. +!web/src/lib/ +web/node_modules/ +web/.next/ +web/out/ + +.claude \ No newline at end of file diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 000000000..c819fdf11 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,48 @@ +# AGENTS.md + +## Repo layout + +``` +projects/ ~270 standalone beginner Python projects, one folder each +web/ Next.js website + in-browser Python playground +data/ static banner images +.github/ CI workflows +``` + +Two independent parts: the **Python projects** and the **website**. They don't +share code. + +## projects/ + +Each project is a self-contained folder (`projects/Hangman/`, `projects/BMI_calculator/`). +No shared package, no repo-wide dependencies — a project lists its own libs in a +local `requirements.txt`/README. Folder naming is inconsistent; match the existing +folder, don't rename. Python is auto-formatted with Black in CI. + +## web/ — system design + +Next.js 16 (App Router, TypeScript, React 19), **statically exported** (`output: 'export'`) +and hosted on **Cloudflare Pages**. Pages are pre-rendered HTML at build time for SEO. + +The **playground** runs real CPython in the browser — no server. Pyodide +(CPython → WebAssembly) loads in a **Web Worker** (`web/public/pyodide-worker.js`). +A `SharedArrayBuffer` + `Atomics` bridge lets blocking `input()` work, which is why +the playground needs cross-origin isolation (COOP/COEP headers in `web/public/_headers`). +The editor is CodeMirror 6; the terminal is xterm.js. + +There is **no backend**. A Cloudflare Worker once executed code server-side — it was +removed; everything runs client-side now. + +Key files: +- `web/src/app/` — routes (`/`, `/projects/[id]`, `/playground/[id]`) +- `web/src/lib/data.ts` — the project list shown on the site +- `web/public/playground/.py` — code preloaded into the playground per project +- `web/src/lib/pyodide/` + `web/public/pyodide-worker.js` — the Pyodide worker + +Only pure-stdlib console projects can run in the playground (`playground: true` in +`data.ts`); pygame/tkinter/network projects cannot. + +Commands (inside `web/`): `corepack pnpm dev` (localhost:3000), `corepack pnpm +run build` (static export → `web/out/`, also runs the type check). The project +uses **pnpm** (pinned via `packageManager` in `package.json`); supply-chain +settings are in `web/pnpm-workspace.yaml`. Do not reintroduce `package-lock.json`. diff --git a/Banner.png b/Banner.png index a29ef27e0..739bcffc4 100644 Binary files a/Banner.png and b/Banner.png differ diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index bf6a6fa87..9d2c44437 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -26,3 +26,23 @@ When you're done, submit a pull request asking for one of the maintainers to che ### Documentation Any piece of code that might be challenging to understand is accompanied by comments. If you add new code or modify existing code in a way that affects its functionality or requires changes in its usage, you must document these changes. + +### Safety and legal checklist + +By contributing, you confirm that you have the right to submit your code, +documentation, data, images, audio, and other materials under this repository's +license. + +Do not submit: + +- API keys, passwords, tokens, credentials, private data, or regulated data. +- Copyrighted images, audio, text, datasets, or code unless you have permission + and include the required attribution/license. +- Malware, credential-stealing code, phishing code, spam tools, unlawful + scraping, unauthorized automation, or code intended to harm people or systems. +- Projects that require users to violate third-party terms of service. + +If a project needs secrets, include only placeholders or a `.env.example` file. +If a project uses third-party APIs, scraping, bots, automation, datasets, or +media assets, document the source, license/terms, and safe usage limits in that +project's README. diff --git a/LEGAL/DISCLAIMER.md b/LEGAL/DISCLAIMER.md new file mode 100644 index 000000000..07f4ea834 --- /dev/null +++ b/LEGAL/DISCLAIMER.md @@ -0,0 +1,29 @@ +# Disclaimer + +Last updated: June 3, 2026 + +This repository and its website are personal hobby projects created for learning, +education, and portfolio demonstration. + +The code, examples, documentation, project descriptions, and website content are +provided "as is" and "as available", without warranties of any kind, express or +implied. I do not guarantee that anything in this project is accurate, complete, +secure, error-free, maintained, or suitable for any particular purpose. + +Use, copy, modify, run, or rely on this project at your own risk. To the maximum +extent permitted by applicable law, I am not responsible for any loss, damage, +claim, liability, legal issue, security issue, data loss, business interruption, +or other problem arising from or related to this project. + +Nothing in this project is professional advice, including legal, financial, +medical, security, business, or educational certification advice. + +Some projects may include APIs, automation, scraping, bots, databases, media +processing, encryption, networking, health or ML-style datasets, or other +higher-risk topics. These examples are educational only. You are responsible for +checking the code, complying with applicable laws and third-party terms, and +using safe test environments. + +If you believe this project contains a legal, copyright, privacy, or security +issue, please contact me through the repository issue tracker or the contact +method listed on the project page. diff --git a/LEGAL/PRIVACY.md b/LEGAL/PRIVACY.md new file mode 100644 index 000000000..e9054cc43 --- /dev/null +++ b/LEGAL/PRIVACY.md @@ -0,0 +1,38 @@ +# Privacy Notice + +Last updated: June 3, 2026 + +This is a personal hobby project. + +## Personal Information + +I do not intentionally collect personal information through this repository or +website. + +If the website includes an in-browser code playground, it is intended to run in +your browser for learning and experimentation. Do not enter private, sensitive, +confidential, or important information into it. + +Do not submit secrets, API keys, passwords, tokens, private documents, regulated +data, or other sensitive information through repository issues, pull requests, +discussion threads, or the playground. + +## Hosting and Platform Logs + +This project may be hosted or distributed through third-party platforms such as +GitHub, Cloudflare Pages, package registries, analytics-free static hosting, or +similar services. Those providers may process technical information such as IP +addresses, browser details, request metadata, logs, cookies, or security signals +according to their own policies. + +I do not control those third-party platforms. + +## Third-Party Links + +This project may link to third-party websites or tools. Their privacy practices +are controlled by their own policies, not by this notice. + +## Contact + +If you believe this project has a privacy issue, please contact me through the +repository issue tracker or the contact method listed on the project page. diff --git a/LEGAL/TERMS.md b/LEGAL/TERMS.md new file mode 100644 index 000000000..e01f21419 --- /dev/null +++ b/LEGAL/TERMS.md @@ -0,0 +1,95 @@ +# Terms of Use + +Last updated: June 3, 2026 + +These Terms of Use apply to this repository, its documentation, and any related +website or playground. + +## Personal Project + +This is a personal hobby project created for learning, education, and portfolio +demonstration. It is not a commercial service, professional product, or managed +platform. + +## No Professional Advice + +The content in this project is for general educational and demonstration +purposes only. It is not legal, financial, medical, security, business, or other +professional advice. + +## No Warranty + +This project is provided "as is" and "as available", without warranties of any +kind, express or implied. I do not guarantee that the code, examples, +documentation, website, playground, or other materials are accurate, complete, +secure, error-free, available, maintained, or suitable for any particular purpose. + +## Use at Your Own Risk + +You are responsible for how you use this project. You should review, test, and +validate any code before using it in your own environment. + +To the maximum extent permitted by applicable law, I am not responsible for any +loss, damage, claim, liability, legal issue, security issue, data loss, business +interruption, or other problem caused by or related to your access to, use of, or +reliance on this project. + +Some projects may include examples involving APIs, automation, scraping, bots, +databases, media processing, encryption, networking, health or ML-style datasets, +or other higher-risk topics. These examples are for learning only. You are +responsible for complying with applicable laws, third-party terms of service, +licenses, platform rules, and safety requirements before running, modifying, or +deploying them. + +## Code Playground + +If this project includes an in-browser code playground, it is provided only for +learning and experimentation. Do not enter private, sensitive, confidential, or +important information into the playground. + +You are responsible for any code you run, copy, modify, or share. + +The playground is not designed for secrets, private data, regulated data, or +production workloads. + +## Third-Party Content, Libraries, and Links + +This project may reference, link to, or depend on third-party websites, libraries, +tools, packages, or services. I do not control third parties and am not +responsible for their content, behavior, availability, security, licensing, or +policies. + +You are responsible for reviewing and complying with third-party terms, +licenses, API rules, robots.txt files, platform rules, and usage limits. + +## Intellectual Property + +Unless a separate license says otherwise, the project is licensed under the +license file included in this repository. + +You are responsible for complying with any applicable third-party licenses, +copyrights, trademarks, and laws when using this project. + +Contributors must only submit code, text, images, audio, data, and other +materials that they have the right to contribute. + +## Acceptable Use + +Do not use this project to break the law, harm others, violate privacy, attack +systems, bypass security, distribute malware, infringe intellectual property, or +misrepresent this project as professional advice or a guaranteed product. + +Do not use this project for unlawful scraping, spam, phishing, credential theft, +unauthorized automation, harassment, surveillance, or any activity that violates +the rights of others. + +## Changes + +I may update, change, remove, or stop maintaining any part of this project at any +time without notice. + +## Contact + +If you believe this project contains a legal, copyright, privacy, or security +issue, please contact me through the repository issue tracker or the contact +method listed on the project page. diff --git a/README.md b/README.md index 09c9967a7..fa07fea74 100644 --- a/README.md +++ b/README.md @@ -1,796 +1,61 @@

- - + + pyBegin — Python Beginner Projects

-GitHub stars -GitHub forks -GitHub license -Awesome + 270+ bite-sized Python projects to learn by building — each one a weekend's worth of fun.

+

+ Live site + Stars + Forks + License + PRs welcome +

-# 💭 **Why these awesome projects ??** -💠 _This repository offers a variety of fascinating mini-projects written in Python._ - -💠 _Working on Python projects will undoubtedly improve your skills and raise your profile in preparation for the globalised marketplace outside._ - -💠 _Projects are a potential method to begin your career in this area._ - -💠 _This language deserves a lot of attention in today's world, and why not since it can address so many real-world problems?_ - - -

📈 Tweet this repository

- - InfiniteGraph Logo +--- -## 📁 All Projects are under [projects](https://github.com/Mrinank-Bhowmick/python-beginner-projects/tree/main/projects) folder. +## 🚀 Try it live — no install needed -

🖥️ Projects So Far ...

+**[pybegin.pages.dev](https://pybegin.pages.dev)** is a searchable gallery of every project in this repo — and **60+ of them run right in your browser**. - - +The playground runs real CPython in the browser via [Pyodide](https://pyodide.org): a live code editor, an interactive console for `input()`, and an annotated, beginner-friendly walkthrough of each project. Pick one, hit **▶ Run code**, and start tinkering — nothing to install. - +> Browse all projects → **[pybegin.pages.dev](https://pybegin.pages.dev)** - +## ✨ Why this repo - +- **270+ projects** — from one-liners to small apps: games, tools, scrapers, GUIs, ML notebooks, and more. +- **Beginner-first.** Every project is small, self-contained, and an ideal first pull request. +- **Learn by reading _and_ running.** The in-browser playground lets you read real code and change it instantly. +- **A genuine open-source on-ramp.** Hundreds of people made their first contribution here. - +## 🏃 Run a project locally - - +```bash +git clone https://github.com/Mrinank-Bhowmick/python-beginner-projects.git +cd python-beginner-projects/projects/ +pip install -r requirements.txt # only if the project ships one +python main.py +``` - +Every project lives in its own folder under [`projects/`](./projects), each with a `README.md` explaining what it does and how to run it. - +## 🤝 Contributing - +New projects and improvements are very welcome — this is a friendly place for your first open-source contribution. - +1. Read [`CONTRIBUTING.md`](./CONTRIBUTING.md) and the [`CODE_OF_CONDUCT.md`](./CODE_OF_CONDUCT.md). +2. Add your project as a new folder in [`projects/`](./projects) with its own `README.md`. +3. Open a pull request. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- - Audiobook - - - - Desktop-Notification - - - - Dice-Roll-Simulator - - - - Madlibs-Generator - -
- - Make-API - - - - Medium Article Reader - - - - Quiz Game - - - - Rock-Paper-Scissors - -
- - Send-Email - - - - Tesla - - - - MorseCode Translator - - - - Weather - -
- - ProjectEuler - - - - AudioRecorder - - - - Hangman - - - - VoiceToText - -
- - TextTranslate - - - - Own_browser - - - - HandCricket - - - - English Thesaurus - -
- - BMI_calculator - - - - Higher-Lower - - - - IPv4_Calculator - - - - KbdXylo - -
- - NASA-APOD - - - - Neurons - - - - Qt5_YouTube - - - - Tic-Tac-Toe - -
- - TurtlePattern - - - - Duplicate-search - - - - Snake-Water-Gun - - - - AES256 - -
- - API Based Weather Report - - - - Audio Converter - - - - BFS visualizer - - - - BMI WebApp - -
- - Bigram_Autocomplete - - - - Bitcoin Mining - - - - BlackJack - - - - Calculator - -
- - Calendar - - - - Captcha_Genrator - - - - Card Game - - - - Connect Four - -
- - Countdown - - - - Dice Simulator - - - - DnD Dice - - - - Drowsiness Detector - -
- - Eye Blink Detection - - - - Fidget Spinner Game - - - - Find_imbd_rating - - - - Flappybird_game - -
- - Full_Calendar - - - - Guess Number - - - - HandCricket - - - - HandTrack - -
- - Hangman - - - - Higher-Lower - - - - Image compressor - - - - Image-to-art - -
- - Internet-speed-test - - - - Inverse Matrix Calculator - - - - JARVIS.PY - - - - Jokenpo - -
- - Jokey - - - - Language-Translate - - - - Location Search App (GUI) - - - - Madlibs Generator - -
- - Mastermind - - - - Minecraft-in-Python-main - - - - Mobile Document Scanner - - - - Mongo CRUD - -
- - Movie recommendation - - - - Number Guessing App - - - - OTP-Verfication-System - - - - OpenCV_color_detect_in_live_feed - -
- - Movie recommendation - - - - Otp_Generator - - - - PDF_Reader - - - - PONG - -
- - Password Projects - - - - Port_Scaner - - - - Print_Colored_Text - - - - ProjectEuler - -
- - Python story generator - - - - QRCode Scanner - - - - QRCode-Generator - - - - QuickWordCloud - -
- - RestrauntAPI - - - - Roll_A_dice - - - - Scientific-Calculator - - - - ScreenRecorder - -
- - Seek_with_hand_track - - - - Slice-Audio - - - - Snake Game - - - - Space Shooter - -
- - Split_Tip - - - - Stock-Market-Dashboard - - - - Space Shooter - - - - Subtitle_synchronizer.py - -
- - Sudoku-Solver - - - - Sudoku_solver - - - - Subtitle_synchronizer.py - - - - Text Editor - -
- - Text to Speech - - - - TextDetection - - - - Timer - - - - Tkinter - -
- - Turtle Pattern - - - - Turtle_Graphics - - - - Twitter-Bot - - - - Watermarker - -
- - Web Scraping Jujustu Kaisen Manga - - - - Website Blocker - - - - YouTube Video Downloader - - - - caesar_cipher - -
- - currency converter - - - - facebook_video_downloader - - - - facerecoginition - - - - game-snake_water_gun - -
- - healthmanagementsystem - - - - maths - - - - minesweeper - - - - pdf_to_text - -
- - ping_pong - - - - proxy-scrapper - - - - reciept generator - - - - scheduledShutdown - -
- - scrap-ycombinator - - - - takeImage - - - - web-crawler(movie extract) - - - - what-for-dinner - -
- - Calculate Age - -
- - -## Run these projects online : - -[![Open in Gitpod](https://gitpod.io/button/open-in-gitpod.svg)](https://gitpod.io/#https://github.com/Mrinank-Bhowmick/python-beginner-projects.git) - - -## Stargazers over time +## ⭐ Stargazers over time [![Stargazers over time](https://starchart.cc/Mrinank-Bhowmick/python-beginner-projects.svg)](https://starchart.cc/Mrinank-Bhowmick/python-beginner-projects) - -

Contributors

@@ -825,8 +90,8 @@ - - PythonicBoat + + itsyashvardhan
Yashvardhan Singh @@ -918,10 +183,10 @@ - - Tyler-Pear + + tylerapear
- Tyler-Pear + Tyler Pearson @@ -1119,32 +384,32 @@ - - Xia3412 + + Harry830
- Xia + Harry830 - - VykSI + + ayan-joshi
- Vishal S Murali + Ayan Joshi - - sb-decoder + + Albinary
- Sowham Bhuin + Albert - - Sameer-choudhary-git + + Blazier07
- Sameer Choudhary + Blazier @@ -1155,34 +420,41 @@ - - MrB141107 + + Sameer-choudhary-git
- Mr.B + Sameer Choudhary - - Albinary + + sb-decoder
- Albert + Sowham Bhuin - - ayan-joshi + + VykSI
- Ayan Joshi + Vishal S Murali - - Harry830 + + Xia3412
- Harry830 + Xia + + + amunjuluri +
+ Anand Munjuluri + + vk0812 @@ -1217,15 +489,15 @@
Hina Ota - + + parth-verma7
Parth Verma - - + sirKiraUzumaki @@ -1260,27 +532,13 @@
Chirag Aggarwal - - - - rahul0x00 -
- Rahul Kumar - - - kom-senapati -
- Kom Senapati - - - - - Subha-5 + + k0msenapati
- Subha Sadhu + K Om Senapati @@ -1298,10 +556,17 @@ - - Ratna2 + + Subha-5
- Ratnadeep Bhowmik + Subha Sadhu + + + + + rahul0x00 +
+ Rahul Kumar @@ -1312,20 +577,6 @@ - - - advik-student-dev -
- Advik Sharma - - - - - tamojeetK -
- Ahaan - - Alex108-lab @@ -1334,10 +585,10 @@ - - amunjuluri + + jpyces
- Anand Munjuluri + Advik Sharma @@ -1353,8 +604,7 @@
Soonam Kalyan Panda - - + Logadheep @@ -1362,6 +612,14 @@ Logadheep + + + tamojeetK +
+ Ahaan + + + MattBlodgettProjects @@ -1370,17 +628,24 @@ - - rajdeepdas2000 + + vrup0408
- Rajdeep Das + VRUSHANG PARIKH - - Preeray + + its-100rabh
- Preeray + Saurabh Mahapatra + + + + + Santhoshnov +
+ Santhosh S @@ -1391,13 +656,20 @@ - - Santhoshnov + + rajdeepdas2000
- Santhosh S + Rajdeep Das + + + Preeray +
+ Preeray + + Nikita0509 @@ -1420,24 +692,17 @@ - - its-100rabh -
- Saurabh Mahapatra - - - - - vrup0408 + + Sayakb03
- VRUSHANG PARIKH + Sayakb03 - - Sayakb03 + + iamshreeram
- Sayakb03 + Shreeram @@ -1448,13 +713,6 @@ Samuel Peters - - - iamshreeram -
- Shreeram - - saanvibk @@ -1476,6 +734,13 @@ Syeda Nowshin Ibnat + + + Toheed07 +
+ Toheed + + RishavRaj20 @@ -1484,13 +749,6 @@ - - - Toheed07 -
- Toheed - - Utkarsh-Raj20 @@ -1525,20 +783,20 @@
Hritik Bhattacharya - - + maglionaire
Maglionaire - + + - - rakinplaban + + lonelyH3b
- Rakin Shahriar Plaban + らきん @@ -1562,14 +820,28 @@ Yest3a + + + rudy3333 +
+ Rudy3 + + + + + kkchx +
+ Kkchx + + + Guillotine189
Sarthak Singhal - - + newtoallofthis123 @@ -1584,13 +856,6 @@ Josh - - - Rathish-Rajendran -
- Rathish R - - siddharth9300 @@ -1599,17 +864,17 @@ - - kkchx + + Rathish-Rajendran
- Kkchx + Rathish R - - rudy3333 + + Ashani-Sansala
- Rudy3 + Ashani Sansala Kodithuwakku @@ -1621,17 +886,24 @@ - - amoghakancharla + + cj-praveen
- Amogha Kancharla + CJ Praveen - - cj-praveen + + akghosh111
- CJ Praveen + Anukiran Ghosh + + + + + amoghakancharla +
+ Amogha Kancharla @@ -1647,22 +919,8 @@
Ankit_Anmol - - - - Ashani-Sansala -
- Ashani Sansala Kodithuwakku - - - - akghosh111 -
- Anukiran Ghosh - - Chloe23077 @@ -1697,14 +955,21 @@
GigabyteZ - - + TimTemi
Flourish + + + + + Ratna2 +
+ Ratnadeep Bhowmik + @@ -1735,10 +1000,10 @@ - - rust-master + + mzaryabrafique
- Rust Master + Muhammad Zaryab Rafique @@ -1778,8 +1043,8 @@ - - WhoIsJayD + + whoisjayd
Jaydeep @@ -1799,13 +1064,6 @@ Harsh Mahadev Duche - - - g0v1ndN -
- Govind S Nair - - Vivek-GuptaXCode @@ -1826,15 +1084,15 @@
Ylavish64 - - + yogesh78026
Yogeshwar Kumar - + + ahmedalhamad7 @@ -1869,15 +1127,15 @@
Prajwal Benedict A - - + chimerson
Emmanuel Ogu - + + Vishvam10 @@ -1912,15 +1170,15 @@
Sumit Baroniya - - + - - SulimanSagindykov + + sagindykovsl
Suliman Sagindykov - + + sudhanshu-77 @@ -1936,8 +1194,8 @@ - - CapedDemon + + spyke7
Shreejan Dolai @@ -1950,20 +1208,20 @@ - - JustProgramJesus + + MamaevSergey
- JustProgramJesus + Мамаев Сергей - - + sdthinlay
Sdthinlay - + + samayita1606 @@ -1971,13 +1229,6 @@ Samayita Kali - - - Polqt -
- Pol Hidalgo - - NishantPacharne @@ -1998,8 +1249,7 @@
Tanawat Jirawttanakul - - + rathoreshreya @@ -2013,7 +1263,8 @@
Shayaanyar - + + samualmartin @@ -2041,8 +1292,7 @@
Prathamesh Phalke - - + Prabinshrestha737 @@ -2056,7 +1306,8 @@
Abhishek Ghimire - + + paartheee @@ -2084,8 +1335,7 @@
Muchamad Yuda Tri Ananda - - + mr-desilva @@ -2099,7 +1349,8 @@
Zainab Ibraheem - + + 0silverback0 @@ -2121,14 +1372,6 @@ Kodingkin - - - kish7105 -
- Kish - - - jonascarvalh @@ -2149,7 +1392,8 @@
Faiz Aslam - + + darshbaxi @@ -2170,8 +1414,7 @@
D-coder111 - - + HimanshuSinghNegi @@ -2192,7 +1435,8 @@
Gargi - + + emanalytic @@ -2213,8 +1457,7 @@
Dishant Nagpal - - + Dhruvil-Lakhtaria @@ -2235,7 +1478,8 @@
David Ioffe - + + Crack-er-jack @@ -2256,8 +1500,7 @@
Bhanushri Chinta - - + ayushi-ras @@ -2278,7 +1521,8 @@
Sudharsan Vanamali - + + hiarijit @@ -2299,8 +1543,7 @@
Anju Chhetri - - + anishaxtha @@ -2321,7 +1564,8 @@
Aleena - + + AdityaSahai123 @@ -2342,8 +1586,7 @@
Abhinandan Singla - - + abc-is-here @@ -2358,20 +1601,14 @@ ARYAN GULATI - - - contra156 -
- Contra - - Surya-29
Surya Narayan - + + RishiPastor05 @@ -2385,8 +1622,7 @@
Ved Sadh - - + Ramisky @@ -2414,7 +1650,8 @@
Praveen SV - + + Pratham-H-S @@ -2428,8 +1665,7 @@
Pranav Dasan - - + Prajwol-Shrestha @@ -2445,8 +1681,8 @@ - - NooBIE-Nilay + + nilay-banerjee
Nilay Banerjee @@ -2457,7 +1693,8 @@
Nischay Goyal - + + nik-6174 @@ -2471,8 +1708,7 @@
Nesh - - + jusinamine @@ -2500,7 +1736,8 @@
MANISH KUMAR CHINTHA - + + LightxAman @@ -2514,8 +1751,7 @@
Kunal Pitale - - + Krishna13515 @@ -2523,13 +1759,6 @@ Krishna13515 - - - Jyothi-Dk -
- Jyothika Dileepkumar - - Josephtobi @@ -2551,5 +1780,13 @@ Jenil Gajjar + + + + Polqt +
+ Pol Hidalgo + + diff --git a/SECURITY.md b/SECURITY.md new file mode 100644 index 000000000..6f309388b --- /dev/null +++ b/SECURITY.md @@ -0,0 +1,34 @@ +# Security Policy + +This is a personal hobby project for education and portfolio demonstration. + +## Reporting a Security Issue + +If you find a security issue, please do not publish exploit details in a public +issue if doing so could harm users or third parties. + +Use GitHub's private vulnerability reporting feature if it is enabled for this +repository. If it is not enabled, contact the maintainer through the contact +method listed on the project page and include only the information needed to +understand the issue. + +## No Secrets + +Do not submit API keys, passwords, tokens, credentials, private documents, +personal data, or regulated data in issues, pull requests, examples, screenshots, +or project files. + +If a project needs credentials, use placeholders such as `.env.example` and +document how users can create their own local secret files. + +## Educational Code + +The code in this repository is not audited, hardened, or guaranteed to be secure. +Review and test everything before running it or reusing it. + +## Higher-Risk Examples + +Projects involving APIs, automation, scraping, bots, networking, encryption, +databases, health or ML-style datasets, or media processing are for learning +only. Use them responsibly, comply with applicable laws and third-party terms, +and test in safe environments. diff --git a/projects/AES256/AES256.py b/projects/AES256/AES256.py index ffa635bcc..ef7e58ceb 100644 --- a/projects/AES256/AES256.py +++ b/projects/AES256/AES256.py @@ -1,16 +1,8 @@ # Imports import hashlib from base64 import b64encode, b64decode -import os -from Cryptodome.Cipher import AES -from Cryptodome.Random import get_random_bytes -import platform - -# Clear the console screen -if platform.system() == "Windows": - os.system("cls") -else: - os.system("clear") +from Crypto.Cipher import AES +from Crypto.Random import get_random_bytes # Start of Encryption Function diff --git a/projects/AES256/README.md b/projects/AES256/README.md index e90d22599..af839fdac 100644 --- a/projects/AES256/README.md +++ b/projects/AES256/README.md @@ -1,19 +1,42 @@ -# AES 256 Encryption and Decryption Algorithm in Python +# AES 256 Encryption and Decryption -This is a beginner friendly project for understanding Encryption/Decryption using AES Encryption Cipher in Python +A beginner-friendly console project demonstrating AES-256 encryption and +decryption in Python. It uses AES in GCM mode (authenticated encryption) with a +key derived from your password via `scrypt`. -## Requirements -1. Cryptodome
-` pip install pycryptodome ` +Choose `1` to encrypt a message (prints the cipher text, salt, nonce and tag) or +`2` to decrypt by entering those values back. -2. PyCryptodomex
-`pip install pycryptodomex ` +## Example -## Setup -1. Python3.x version should be installed in your system. -2. Install all requirements. -3. Clone the repository. -4. Run Python File `python3 AES256.py` +```text + AES 256 Encryption and Decryption Algorithm + ------------------------------------------- -## Demo! -![Screenshot 2022-10-20 134838](https://user-images.githubusercontent.com/99896373/196895153-c0e40bb4-95e8-4d98-86bd-eb0f051c218a.png) +Enter 1 to encrypt and 2 to decrypt: 1 +Enter the Password: hunter2 + +Enter the Secret Message: meet me at noon + +Encrypted: +--------------- + +cipher_text: 9pX2k7Qe1A== +salt: Hh0r2Hk9pQqVz8m1Yw3aBQ== +nonce: Lm4nKp7Rt2sVx8yZ +tag: Tz1qWe4rUi7oPa2sDf5gHj== +``` + +To recover the message, run the program again, choose `2`, and enter the four +values above along with the same password. + +## How to run on localhost + +```bash +pip install pycryptodomex +python AES256.py +``` + +## Dependencies + +- `pycryptodomex` — the `Cryptodome` AES implementation diff --git a/projects/API Based Weather Report/README.md b/projects/API Based Weather Report/README.md index 050d7b185..3992d3bfd 100644 --- a/projects/API Based Weather Report/README.md +++ b/projects/API Based Weather Report/README.md @@ -13,6 +13,26 @@ Welcome to the Weather Information App! This application allows users to fetch c - Python 3.x installed on your system. - OpenWeatherMap API key. You can obtain it by signing up at [OpenWeatherMap](https://home.openweathermap.org/users/sign_up). +## Example + +```text +Welcome to the Weather Information App! +You need an API key to access weather data from OpenWeatherMap. +You can obtain your API key by signing up at https://home.openweathermap.org/users/sign_up +Please enter your OpenWeatherMap API key: YOUR_API_KEY +Enter the city name: London +Enter the temperature unit. 'C' for Celsius and 'F' for Fahrenheit: C +Current City : London, GB +Current temperature is: 15.2 C +Current weather desc : light rain +Current Humidity : 82 % +Current wind speed : 5.1 kmph +Current wind direction: SW +Today's sunrise time : 05:12:34 +Today's sunset time : 20:45:12 +Weather information written to weatherinfo.txt +``` + ## Usage 1. Obtain your OpenWeatherMap API key by signing up at [OpenWeatherMap](https://home.openweathermap.org/users/sign_up). @@ -42,7 +62,6 @@ Welcome to the Weather Information App! This application allows users to fetch c - Alternative Names: Use alternative or local names if known (e.g., "Mumbai" for "Bombay"). - City Name with Spaces: Input the city name with spaces as it appears (e.g., "Los Angeles", "San Francisco"). - City District or Area (Optional): Specify a district or area within larger cities for more localized weather data (e.g., "Manhattan, New York", "Shinjuku, Tokyo"). - ## License This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details. diff --git a/projects/AWS_s3_upload/readme.md b/projects/AWS_s3_upload/readme.md index ffdd64bfe..9978951ac 100644 --- a/projects/AWS_s3_upload/readme.md +++ b/projects/AWS_s3_upload/readme.md @@ -1,13 +1,30 @@ - ## Simple Python script for AWS S3 file upload. ### Prerequisites + boto3 (pip install boto3)
-### How to run the script +### Example + +After filling in the credentials and file details in `main.py` and running +`python main.py`, the console prints: + +```text +Upload Successful +``` + +If the local file cannot be found the output is: + +```text +The file was not found +``` + +### How to run on localhost the script + - Specify both ACCESS_KEY and SECRET_KEY. You can get them both on your AWS account in "My Security Credentials" section.
- Specify the local file name, bucket name and the name that you want the file to have inside s3 bucket using LOCAL_FILE, BUCKET_NAME and S3_FILE_NAME variables.
- Run "python main.py"
### Author Name -Yashvardhan Singh https://github.com/pythonicboat \ No newline at end of file + +Yashvardhan Singh https://github.com/pythonicboat diff --git a/projects/Adjactive_compartive_superlative/README.md b/projects/Adjactive_compartive_superlative/README.md new file mode 100644 index 000000000..11ff57fc0 --- /dev/null +++ b/projects/Adjactive_compartive_superlative/README.md @@ -0,0 +1,30 @@ +# Adjective Comparative & Superlative + +A console tool that takes a comma-separated list of adjectives and prints the +comparative and superlative form of each, using WordNet (via NLTK) with a +JSON fallback list of irregular adjectives. + +## Example + +```text +Enter a list of adjectives (comma-separated): happy, bad, large + +Adjective Comparative Superlative +------------------------------------------ +happy happier happiest +bad worse worst +large more large most large +``` + +## How to run on localhost + +```bash +pip install -r requirements.txt +python adjCS.py +``` + +On first run NLTK downloads the `wordnet` corpus. + +## Dependencies + +- `nltk` — and its `wordnet` corpus (downloaded at runtime) diff --git a/projects/Advisor/README.md b/projects/Advisor/README.md new file mode 100644 index 000000000..a1eadb1be --- /dev/null +++ b/projects/Advisor/README.md @@ -0,0 +1,26 @@ +# Random Advisor + +A small Tkinter desktop app that fetches a random piece of advice from the +[Advice Slip API](https://api.adviceslip.com/) and shows it in a window. Click +**Get Advice** for a new one. + +## Example + +1. The window titled "Random Advisor Application" opens and immediately fetches a + piece of advice, displaying it in the centre of the window (e.g. "Always be + yourself; everyone else is already taken."). +2. Click **Get Advice** to fetch a new random tip from the Advice Slip API. +3. The label updates with the new advice text. +4. Close the window to exit. + +## How to run on localhost + +```bash +pip install requests +python advisor.py +``` + +## Dependencies + +- `requests` — to call the Advice Slip API +- `tkinter` — GUI (ships with the standard Python installer) diff --git a/projects/Alarm Clock/README.md b/projects/Alarm Clock/README.md new file mode 100644 index 000000000..a525ec30a --- /dev/null +++ b/projects/Alarm Clock/README.md @@ -0,0 +1,32 @@ +# Alarm Clock + +A Tkinter desktop alarm clock. Pick an hour, minute and second from the +drop-downs, press **Set Alarm**, and when the system clock reaches that time it +plays `sound.wav` on a loop until you press **Stop Alarm**. + +The folder also contains `clock.py`, a standalone digital clock that shows the +current time and greets you based on the time of day. + +## Example + +1. The window opens showing three drop-down menus labelled with hours, minutes, + and seconds, along with **Set Alarm** and **Stop Alarm** buttons. +2. Select `07`, `30`, `00` from the drop-downs to set an alarm for 07:30:00. +3. Click **Set Alarm**. The program checks the system clock once per second in + the background, printing `07:29:55 07:30:00` to the console each tick. +4. When the system clock reaches `07:30:00`, `sound.wav` starts playing on a + loop and "Wake Up now!" is printed to the console. +5. Click **Stop Alarm** to stop the sound. + +## How to run on localhost + +```bash +pip install pygame +python alarm_clock.py # the alarm +python clock.py # the digital clock +``` + +## Dependencies + +- `tkinter` — GUI (ships with the standard Python installer) +- `pygame` — plays the alarm sound (`alarm_clock.py` only) diff --git a/projects/Amazon Product Availbility Checker/README.md b/projects/Amazon Product Availbility Checker/README.md new file mode 100644 index 000000000..d0f88d85a --- /dev/null +++ b/projects/Amazon Product Availbility Checker/README.md @@ -0,0 +1,36 @@ +# Amazon Product Availability Checker + +A console script that fetches an Amazon product page, parses it with +BeautifulSoup, and reports whether the product is in stock. + +Before running, edit `amazon.py`: + +- Set `product_url` to the Amazon product page you want to track. +- Set a valid `User-Agent` string in `headers` (Amazon blocks the default one). + +## Example + +After setting `product_url` and `User-Agent` in `amazon.py` and running the +script, the console prints one of: + +```text +Wireless Bluetooth Headphones is available on Amazon. +``` + +or + +```text +Wireless Bluetooth Headphones is currently out of stock on Amazon. +``` + +## How to run on localhost + +```bash +pip install requests beautifulsoup4 +python amazon.py +``` + +## Dependencies + +- `requests` — fetches the product page +- `beautifulsoup4` — parses the HTML diff --git a/projects/AnalogClock/readme.md b/projects/AnalogClock/readme.md index 1903813bc..bd675ae38 100644 --- a/projects/AnalogClock/readme.md +++ b/projects/AnalogClock/readme.md @@ -1,4 +1,27 @@ -## Analog Clock -1.This script Creates a popup with analog clock using tkinter -it's always start at 10 o'clock thats a fact -![img.png](img.png) \ No newline at end of file +# Analog Clock + +A Tkinter program that draws a working analog clock on a canvas — face, hour +numbers, and moving hour/minute/second hands. The clock always starts at +10 o'clock and ticks forward once per second. + +![img.png](img.png) + +## Example + +1. Run `python analog_clock.py`. A window opens showing a circular clock face + with hour numbers 1–12 drawn around the edge. +2. The clock starts at 10 o'clock with all three hands positioned accordingly. +3. Every second the second hand advances one tick; the minute and hour hands + move proportionally. +4. Close the window to exit. + +## How to run on localhost + +```bash +python analog_clock.py +``` + +## Dependencies + +- `tkinter` — GUI (ships with the standard Python installer) +- `math` — standard library diff --git a/projects/Audio Converter/README.md b/projects/Audio Converter/README.md index 1bff5acaf..92f9cac04 100644 --- a/projects/Audio Converter/README.md +++ b/projects/Audio Converter/README.md @@ -10,6 +10,14 @@ Use the package manager [pip](https://pip.pypa.io/en/stable/) to install pydub. pip install pydub ``` +## Example + +```text +$ python audioconverter.py song.mp3 wav +Converting from mp3 to wav +File saved to /home/user/music/song.wav +``` + ## Usage ```bash diff --git a/projects/AudioAPI/ReadMe.md b/projects/AudioAPI/ReadMe.md index 71e78a9f5..72b19f499 100644 --- a/projects/AudioAPI/ReadMe.md +++ b/projects/AudioAPI/ReadMe.md @@ -17,6 +17,25 @@ Before using the Unofficial Whisper API, ensure you have the following prerequis ```bash pip install Flask +## Example + +1. Start the server by running `python transcription.py`. Flask listens on + `http://localhost:5000`. +2. From another terminal, send an audio file with: + ``` + curl -X POST -F "audio=@recording.mp3" http://localhost:5000/transcribe + ``` +3. The server loads the Whisper model, transcribes the audio, and returns a + `subtitles.vtt` file as a download containing timestamped transcript + segments, e.g.: + ``` + WEBVTT + + 1 + 0:00:00.000 --> 0:00:04.000 + Hello, welcome to the demonstration. + ``` + ## Getting Started 1. Clone the repository diff --git a/projects/AudioRecorder/README.md b/projects/AudioRecorder/README.md new file mode 100644 index 000000000..d13146bea --- /dev/null +++ b/projects/AudioRecorder/README.md @@ -0,0 +1,25 @@ +# Audio Recorder + +Records audio from the system microphone and saves it to RAW, WAV, AIFF, and FLAC files. + +## Example + +```text +Listening +``` + +Speak into the microphone. When you finish, the program saves the recording to +`microphone-results.raw`, `microphone-results.wav`, `microphone-results.aiff`, +and `microphone-results.flac` in the current directory. + +## How to run on localhost + +``` +pip install SpeechRecognition pyaudio +python main.py +``` + +## Dependencies + +- SpeechRecognition +- pyaudio (microphone input backend) diff --git a/projects/Audiobook/Readme.md b/projects/Audiobook/Readme.md index e994be46f..8f1fb332b 100644 --- a/projects/Audiobook/Readme.md +++ b/projects/Audiobook/Readme.md @@ -8,6 +8,15 @@ This Python script uses `pyttsx3` and `PyPDF2` to read the text content of a PDF - `PyPDF2`: A library to handle PDF files. - `keyboard`: A library to listen for keyboard events. +## Example + +```text +Enter your PDF file name: sample.pdf +``` + +The program begins reading the PDF aloud, page by page, using the system +text-to-speech engine. Press **q** at any time to stop playback. + ## Usage 1. Install the required libraries using pip: diff --git a/projects/AutoGui/ReadMe.md b/projects/AutoGui/ReadMe.md index 370332a52..92497bcb9 100644 --- a/projects/AutoGui/ReadMe.md +++ b/projects/AutoGui/ReadMe.md @@ -2,8 +2,19 @@ This Python script periodically moves the mouse and performs a click action. It’s useful for keeping the system active to avoid timeouts or showing as idle in applications like Microsoft Teams. +## Example + +1. Run `python AutoGui.py`. The script runs silently in the background. +2. Every 20 seconds the mouse moves 100 pixels diagonally and then returns to + its original position, followed by a click. +3. This keeps the system active and prevents idle status in applications such + as Microsoft Teams. +4. Press **Ctrl+C** in the terminal to stop the script. The console prints: + ```text + Script terminated by user + ``` + ## Features - Moves the mouse slightly every 20 seconds - Simulates a mouse click periodically - Prevents idle status on Microsoft Teams - diff --git a/projects/BFS visualizer/Readme.md b/projects/BFS visualizer/Readme.md index f77f229c7..037261151 100644 --- a/projects/BFS visualizer/Readme.md +++ b/projects/BFS visualizer/Readme.md @@ -2,6 +2,18 @@ This project helps us to visualize BFS algorithm by searching end point from start in a maze. +## Example + +1. Run `python main.py`. A curses terminal window opens displaying the 9x8 maze + with `#` walls, spaces for open paths, `O` as the start position, and `X` as + the end. +2. The BFS algorithm explores cells level by level. Each visited cell on the + current path is highlighted in red (`X`) while the walls and open cells are + shown in green. +3. After a 0.2-second delay per step, the algorithm finds the shortest path from + `O` to `X` and the final path remains highlighted on screen. +4. Press any key to exit. + # Tech Stack: Python @@ -13,4 +25,4 @@ # Output: -![output](./output.gif) \ No newline at end of file +![output](./output.gif) diff --git a/projects/BMI WebApp/README.md b/projects/BMI WebApp/README.md new file mode 100644 index 000000000..354ecc2f3 --- /dev/null +++ b/projects/BMI WebApp/README.md @@ -0,0 +1,26 @@ +# BMI WebApp + +A small BMI calculator built with PyWebIO. It asks for height and weight in a browser form and reports the BMI along with a weight classification. + +## Example + +1. Run `python main.py`. PyWebIO opens a browser page with two input fields. +2. Enter your height in metres (e.g. `1.75`) and your weight in kilograms + (e.g. `70`). +3. The page displays the result, for example: + ``` + Your BMI is 22.857142857142858 and the person is : normal + ``` +4. Different weight ranges produce classifications such as "underweight", + "overweight", or "severely obese". + +## How to run on localhost + +``` +pip install pywebio +python main.py +``` + +## Dependencies + +- pywebio diff --git a/projects/BMI_calculator/Readme.md b/projects/BMI_calculator/Readme.md index e94470795..43d4f738b 100644 --- a/projects/BMI_calculator/Readme.md +++ b/projects/BMI_calculator/Readme.md @@ -2,6 +2,25 @@ This Python script calculates Body Mass Index (BMI) based on a person's height and weight. It then interprets the BMI to provide a classification ranging from underweight to clinically obese. +## Example + +```text +Here You can take the reference chart + +╒════════════════╤═════════════════╕ +│ BMI │ Weight Status │ +╞════════════════╪═════════════════╡ +│ Below 18.5 │ Underweight │ +│ 18.5 – 24.9 │ Normal weight │ +│ 25.0 – 29.9 │ Overweight │ +│ 30.0 and above │ Obese │ +╘════════════════╧═════════════════╛ + +Enter your height in meters: 1.75 +Enter your weight in kilograms: 68 +Your BMI is 22.2, you have a normal weight. +``` + ## How to Use 1. Make sure you have Python installed on your system. @@ -13,7 +32,7 @@ This Python script calculates Body Mass Index (BMI) based on a person's height a 4. Run the script by executing the following command: ```bash - python bmi_calculator.py + python "BMI calculator.py" ``` 5. Follow the on-screen instructions to input your height (in meters) and weight (in kilograms). @@ -22,7 +41,7 @@ This Python script calculates Body Mass Index (BMI) based on a person's height a ## Code Structure -- `bmi_calculator.py`: The main Python script containing the BMI calculation and interpretation logic. +- `BMI calculator.py`: The main Python script containing the BMI calculation and interpretation logic. - `README.md`: This file, providing an overview of the BMI calculator and usage instructions. ## Functions diff --git a/projects/Battleship/README.md b/projects/Battleship/README.md index 3b8026773..cf7fe155e 100644 --- a/projects/Battleship/README.md +++ b/projects/Battleship/README.md @@ -27,6 +27,43 @@ The game handles incorrect entries and can be replayed repeatedly. +## Example + +```text +Do you want to start a new game of Battleship? yes +Enter a number between 5 and 15. + +This will determine how big the playing board is and how many turns you have to find the Battleship. (5 rows, 5 columns, 5 turns, etc.): 5 +Welcome to Battleship. + +A ship, one cell long, has been randomly placed on the below 5x5 grid. +You have 5 turns to find it. + +O O O O O +O O O O O +O O O O O +O O O O O +O O O O O + +Turn 1 of 5 + +Guess Row: 3 +Guess Column: 2 +Miss! + +O O O O O +O O O O O +O O O O O +O O X O O +O O O O O + +Turn 2 of 5 + +Guess Row: 1 +Guess Column: 4 +Congratulations! You sank my battleship! +``` + ## Installation Download main.py, change to the directory where you downloaded the file and run it using `python3 main.py` @@ -55,5 +92,3 @@ Py-Battleship is built with the following tools and libraries: