Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add python docs #108

Draft
wants to merge 4 commits into
base: main
Choose a base branch
from
Draft
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
124 changes: 79 additions & 45 deletions hyperbook/book/entwicklung/eine-idee-implementieren.md
Original file line number Diff line number Diff line change
@@ -1,14 +1,14 @@
---
name: Idee implementieren
index: 8
index: 2
---

# Eine Idee implementieren

Man hat einige Spiele absolviert und sich eine gute Strategie
ausgedacht. Damit hat man zwar schon einen wichtigen Teil der Arbeit
geleistet, aber irgendwie muss dem
[Computerspieler](software/client) noch beigebracht werden, nach
[Computerspieler](/glossary/player) noch beigebracht werden, nach
dieser Strategie zu spielen.

Anhand einer kleinen Aufgabe soll gezeigt werden, wie man eine Idee
@@ -34,53 +34,87 @@ zunächst beschreiben, wie man als Mensch vorgehen würde.

3. Die kleinste Karte ist jetzt an der richtigen Position.

4. Führe die Schritte nochmal für den Reststapel (ohne die sortierten
4. Führe die Schritte immer wieder für den Reststapel (ohne die sortierten
Karten) aus.

### Idee implementieren

Nachdem man seine Idee formal niedergeschrieben hat, kann sie ganz
leicht in ein Programm überführt werden:

/**
* Das Array a[] symbolisiert den Stapel der unsortierten Karten. Dabei steht
* eine Zahl immer für eine spezielle Karte. Eine kleinere Zahl bedeutet,
* dass es sich um eine kleinere Karte handelt.
*
* start gibt die Position an, wo der Reststapel beginnt (am Anfang: start = 0)
*/
public static void sortiere(int[] a, int start) {
//Position der kleinsten Karte
int pos = start;

// Gehe Array durch und merke die Position der kleinsten Karte
for (int i = start+1; i < a.length; i++) {
// Wenn eine kleinere Karte gefunden wurde...
if (a[i] < a[pos]) {

... neue Position merken
pos = i;
}
}

// kleinste Karte mit erster Karte des Reststapels tauschen
int temp = a[start]; // erste Karte merken
a[start] = a[pos]; // kleinste Karte nach vorne bringen
a[pos] = temp; // gemerkte Karte in die Mitte des Stapels schreiben

// Wenn es noch einen Reststapel gibt, soll dieser weitersortiert werden
if (start < a.length) {
sortiere(a, start+1);
}
}

- Gehe den Stapel durch und merke die Position, an der sich die
kleinste Karte befindet.

- Tausche die Position der kleinsten Karte mit der untersten Karte im
Stapel.

- Die kleinste Karte ist jetzt an der richtigen Position.

- Führe die Schritte nochmal für den Reststapel (ohne die sortierten
Karten) aus.
#### Java

```java
/**
* Das Array a[] symbolisiert den Stapel der unsortierten Karten. Dabei steht
* eine Zahl immer für eine spezielle Karte. Eine kleinere Zahl bedeutet,
* dass es sich um eine kleinere Karte handelt.
*
* start gibt die Position an, wo der Reststapel beginnt (am Anfang: start = 0)
*/
public static void sortiere(int[] a, int start) {
// Position der kleinsten Karte
int pos = start;

// Gehe Array durch und merke die Position der kleinsten Karte
for (int i = start+1; i < a.length; i++) {
// Wenn eine kleinere Karte gefunden wurde...
if (a[i] < a[pos]) {

// ... neue Position merken
pos = i;
}
}

// kleinste Karte mit erster Karte des Reststapels tauschen
int temp = a[start]; // erste Karte merken
a[start] = a[pos]; // kleinste Karte nach vorne bringen
a[pos] = temp; // gemerkte Karte in die Mitte des Stapels schreiben

// Wenn es noch einen Reststapel gibt, soll dieser weitersortiert werden
if (start < a.length) {
sortiere(a, start+1);
}
}
```

#### Python

```python
# Die Liste a symbolisiert den Stapel der unsortieren Karten als Zahlen repräsentiert.
# Dabei steht eine immer für eine spezielle Karte. Eine kleinere Zahl bedeutet,
# dass es sich um eine kleinere Karte handelt.
#
# start gibt die Position an, wo der Reststapel beginnt (am Anfang: start = 0)
#
# Beachte: in Python müssen Datentypen nicht explizit angegeben werden, es hilft aber
# möglicherweise bei der Entwicklung
def sortiere(a: list[int], start: int):
# Position der kleinsten Karte
pos = start

# Gehe die Liste durch und merke die Position der kleinsten Karte
for i in range(start + 1, len(a)):
# Wenn eine kleinere Karte gefunden wurde...
if a[i] < a[pos]:

# ... neue Position merken
pos = i;

# kleinste Karte mit erster Karte des Reststapels tauschen
temp = a[start]; # erste Karte merken
a[start] = a[pos]; # kleinste Karte nach vorne zum sortierten Bereich bringen
a[pos] = temp; # gemerkte Karte in die Mitte des Stapels schreiben

# Wenn es noch einen Reststapel gibt, soll dieser weitersortiert werden,
# ansonsten gebe die sortierte Liste zurück
if start < len(a) - 1:
return sortiere(a, start+1);
else:
return a
```

## Weiterführende Links

Wir haben hier den Sortieralgorithmus [Selection Sort](https://de.wikipedia.org/wiki/Selectionsort)
rekursiv implementiert.
12 changes: 10 additions & 2 deletions hyperbook/book/entwicklung/index.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
---
name: Entwicklung eines Computerspielers
index: 2
index: 1
expanded: true
---

@@ -13,7 +13,7 @@ die den Start mit der Entwicklung erleichtern soll.
## Die richtige Programmiersprache

Am einfachsten ist es natürlich,
eine der offiziellen Spielervorlagen (Java, Ruby, Python) als Basis zu nutzen,
eine der offiziellen Spielervorlagen (Java, Python) als Basis zu nutzen,
allerdings könnt ihr auch eigene Clients in anderen Sprachen schreiben.
Das ist mit mehr Arbeit verbunden,
aber wenn ihr eine Sprache besonders gerne nutzt oder Vorteile seht,
@@ -51,3 +51,11 @@ welches man bei Galileo Computing als
[Open-Book](http://openbook.galileocomputing.de/javainsel)
kostenlos online betrachten und herunterladen kann.
Man kann es dort ebenfalls als gedruckte Ausgabe bestellen.

### Python

Für Python gibt es eine direkt von der Python Organisation bereit gestellte Dokumentation.
Diese ist für die Version 3.12.8 [hier](https://docs.python.org/3.12/) verfügbar und enthält auch ein Python-Tutorial.
Wem das etwas unübersichtlich vorkommt, kann sich auch die bekannte Plattform [w3schools](https://www.w3schools.com/python/)
zum Thema Python anschauen. Beide Ressourcen sind auf Englisch, aber es lassen sich sowohl im Text,
als auch im Videoformat, viele weitere Einführungen in die Sprache Python im Internet finden.
File renamed without changes.
5 changes: 5 additions & 0 deletions hyperbook/book/entwicklung/java/index.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,5 @@
---
name: Java
index: 3
expanded: false
---
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
---
name: Installation von Java
index: 5
index: 1
---

# Installation von Java
2 changes: 1 addition & 1 deletion hyperbook/book/entwicklung/kennenlernen.md
Original file line number Diff line number Diff line change
@@ -7,7 +7,7 @@ index: 1

Um ein Computerprogramm zu schreiben, was ein Spiel spielen kann, muss
man vorher das Spiel selbst verstehen und spielen können.
Dabei könnt ihr euch bereits Ideen und Strategien entwickeln,
Dabei könnt ihr bereits Ideen und Strategien entwickeln,
die ihr in euren :t[Computerspieler]{#player} nachher umsetzen wollt.

Das Spiel selbst kann zu zweit oder allein gegen den [Zufallsspieler](glossary/client#der-simpleclient)
73 changes: 73 additions & 0 deletions hyperbook/book/entwicklung/python/1-installation-von-python.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,73 @@
---
name: Installation von Python
index: 1
---

# Installation von Python

Um einen Computerspieler für die Software-Challenge in Python entwickeln zu können,
müssen einige Vorraussetzungen erfüllt sein.
Diese Anleitung soll die Vorbereitung und Installation erleichtern.

## Grundsätzliches

Wir bieten die Abgabe eines Python Computerspieler in den Python-Versionen 3.10.x und 3.12.x an
(dabei steht x für eine beliebige Unterversion).

In den folgenden Abschnitten wird hauptsächlich die neuere Version 3.12.x gezeigt, aber wenn bei gewissen Befehlen
`312` oder `3.12` verwendet wird, kann analog für Version 3.10.x auch `310` bzw `3.10` verwendet werden.
Wenn es größere Unterschiede zwischen den Versionen gibt, wird das detailliert erklärt.

## Installation

Der Download des Python-Installers geschieht über die offizielle Seite der
[Python Organisation](https://www.python.org/downloads/).
Dort kann man weiter unten in einer Tabelle die neueste Unterversion von Python 3.12 heraussuchen
und diese herunterladen.

![Beispiel für Download](/images/python/download.png)

Man wählt dann auf der Download-Seite den Installer für das eigene System und führt diesen nach dem Download aus.
Im (Windows-)Installer hat man dann die Möglichkeit python.exe zu den Umgebungsvariablen (PATH) hinzuzufügen,
was zu empfehlen ist. Dann kann man die einfache Installation starten.
Dabei wird auch der Paket-Manager pip installiert, welcher in Zukunft noch gebraucht wird.

### Überprüfung

Nach der Installation kann man mit dem Terminal überprüfen, ob die Installation erfolgreich war.
Dafür fragt man die Versionen der Programme Python und pip mit folgenden Befehlen ab:

```bash
python --version
```

```bash
pip --version
```

Bei Python sollte die ausgewählte Version ausgegeben werden und für pip müsste irgendeine Version vorhanden sein,
die mit einem Dateipfad auf den Ordner der installierten Python-Version verweist.

Wenn das geklappt hat, ist man bereit für den nächsten Step.

### socha-Paket

Um nun auf die bereitgestellte Schnittstelle für einen Python Computerspieler zugreifen zu können,
muss das entsprechende Paket mit Hilfe von pip und folgendem Befehl über ein Terminal installiert werden:

```bash
pip install socha
```

Dabei sollte automatisch die neueste Version verwendet werden,
welche in der Release Übersicht des offiziellen [Github-Repository](https://github.com/software-challenge/player-python/)
zur Python Schnittstelle gefunden werden kann:

![Release Übersicht](/images/python/socha-releases.png)

Falls nicht die aktuelleste Version installiert wurde, kann man den Befehl auch erweitern,
um eine spezielle Version auszuwählen (natürlich Version entsprechend anpassen):

```bash
pip install socha==3.6.2
```
Original file line number Diff line number Diff line change
@@ -0,0 +1,48 @@
---
name: Einrichtung der Entwicklungsumgebung
index: 2
---

# Einrichtung der (Python-)Entwicklungsumgebung

Python Code lässt sich mit jedem Text Editor schreiben.
Wenn man weitere nützliche Features neben dem einfachen Editor haben möchte,
sollte man zu einer integrierten Entwicklungsumgebung (IDE) greifen,
welche das Arbeiten wirklich erleichtert.

Im Folgenden wird die Einrichtung von [Visual Studio Code](https://code.visualstudio.com/)
(eine IDE von Microsoft, die für sämtliche Sprachen geeignet ist) gezeigt.
Aber auch Umgebungen wie [PyCharm](https://www.jetbrains.com/pycharm/),
welche ausschließlich für Python entworfen wurden, sind beliebt.

**Hinweis:** Bevor die IDE eingerichtet wird, sollten [Python und pip](installation-von-python) erfolgreich
installiert sein.

## Visual Studio Code einrichten

### Installation

Die einfachste Installation geschieht mit Hilfe des VS Code Installers von
der [Download-Seite](https://code.visualstudio.com/Download). \
Nachdem man den die Installer Datei heruntergeladen hat,
gelangt man im Browser auf eine [Seite](https://code.visualstudio.com/docs/),
die das Aufsetzen sehr detailliert erklärt.

Die wichtigsten Schritte bzgl. der Software-Challenge werden hier noch erklärt:

#### Installer

Der Installer wird ausgeführt und alle Features, die installiert werden sollen,
müssen auswählt werden. Dabei lassen sich alle Optionen empfehlen.

### Python in VS Code

Um die angespochenen Unterstützungen für Python nutzen zu können,
muss man in VS Code eine Erweiterung installieren:

1. Im linken Menü auf "Extensions" gehen
2. Nach "Python" suchen
3. Die "Python" Erweiterung von Microsoft auswählen
4. Das Paket installieren

![Python in VS Code](/images/python/vs-code-python.png)
105 changes: 105 additions & 0 deletions hyperbook/book/entwicklung/python/3-getting-started.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,105 @@
---
name: Getting Started
index: 3
---

# Getting Started

Damit man nicht bei null starten muss, wird eine grundlegende Code-Basis bereitgestellt.
Diese importiert die wichtigsten Funktionen des installierten socha-Pakets und nutzt diese,
um eine simple, aber trotzdem schon spielfähige Logik zu implementieren.
Aktuell gibt diese Vorlage jedoch nur zufällige Züge an den [Spielserver](/glossary/server) zurück.

## Projekt erstellen

Alles beginnt mit einem Ordner auf dem Computer, der komplett nach eigenen Wünschen benannt
werden kann. In diesen Ordner werden ab sofort alle Dateien für den Computerspieler abgelegt.

Die Spielervorlage kann komplett aus dem
[Github-Repository](https://github.com/software-challenge/player_python/blob/master/logic.py)
des socha-Pakets in den eben erstellten Ordner heruntergeladen werden.

Standardmäßig heißt diese Datei `logic.py`, doch die tatsächliche Bezeichnung ist ebenfalls
einem selbst überlassen. Für die Zukunft ist nur zu beachten, dass alle Befehle mit

```bash
python logic.py ...
```

an den gewählten Dateinamen angepasst werden.

## Visual Studio Code Oberfläche

Wenn man noch nie mit so einer Entwicklungsumgebung gearbeitet hat,
mag der erste Anblick wohl ziemlich unübersichtlich sein. Doch wenn man sich
länger mit der Software befasst, fällt einem das schnell leichter und
man möchte die modernen Tools gar nicht mehr missen.
Deshalb folgt in diesem Abschnitt eine Erläuterung der wichtigsten
Komponenten, die Visual Studio Code zu bieten hat:

![VS Code Oberfläche](/images/python/vs-code.png)

### Datei Explorer

Im Datei/Projekt Explorer auf der linken Seite, welcher über den markierten Button
erreichbar ist, werden alle Unterordner und Dateien des mit Visual Studio Code geöffnete
Ordners angezeigt. Mit einem Rechtsklick auf eine Datei/ einen Ordner öffnet sich ein
ausführliches Dropdownmenü mit Funktionen wie Umbenennen und Kopieren, wie man es vom
System Explorer kennt.

Um den Ordner des Computerspielers zu öffnen, hat man zwei einfache Möglichkeiten:

1. Oben auf "File" klicken und dann bei "Open Folder" den entsprechenden Ordner auswählen.
2. Im System Dateiexplorer den Ordner rechtsklicken und "Mit Code öffnen" auswählen.
(Das geht nur wenn man diese Option bei der VS Code Installation ausgewählt hat)

### Registerkarten

Wenn man eine Datei aus dem Explorer öffnet, wird oben in der Reihe eine
neue Registerkarte mit dieser Datei erstellt.
Ähnlich wie bei Internet Browsern hat man so schnellen Zugriff auf die Dateien,
an welchen man aktuell arbeitet.

### Editor

Das Herzstück einer Entwicklungsumgebung. Hier in der Mitte wird der eigentliche Code geschrieben.
Es lassen sich auch mehrere Editor-Bereiche nebeneinander erstellen, wenn man einzelne Registerkarten
per Drag-and-Drop an z.B. den rechten Rand des Editors zieht.

### Terminal

Das Terminal im unteren Bereich ist nicht dauerhaft sichtbar, sondern kann über den Button "Terminal" und dann
"New Terminal" (am oberen Bildschirmrand) geöffnet werden. Oder man wartet bis man das
[Python Sktipt startet](#starte-skript), wodurch sich das Terminal automatisch öffnen wird.

Im Terminal können alle möglichen Befehle ausgeführt werden, wie z.B. das Starten eines Python Programms,
aber auch Paketverwaltung mit pip ist darüber möglich. Hier werden auch Outputs der ```print()``` Funktion
von Python, sowie Fehlermeldungen des Programms angezeigt.
Letztendlich handelt es sich genauso um eine Terminalanwednung, wie sie auch vom System bereitgestellt wird.
Man könnte also auch diese nutzen, wenn einem das lieber ist.

### Python Version

Wenn man ein Python Skript geöffnet hat, kann man unten rechts erkennen, dass Visual Studio Code die
Programmiersprache erkannt hat und welche Version des Python-Interpreters von VS Code verwendet wird.
Diese sollte eigentlich automatisch erkannt werden, insofern die Python Installation vorher erfolgreich war. \
Durch einen Klick auf die Version öffnet sich am oberen Bildschirmrand aber auch ein Pop-Up,
wo man die Möglichkeit bekommt, manuell eine installierte Python Version auszuwählen.

### Starte Skript

Der Play-Button oben rechts macht eigentlich genau das was man denkt:

Es öffnet sich das VS Code Terminal und das aktuell geöffnete Skript wird ausgeführt.

### Erweiterungen

Dieses Bereich wurde bei der Installation der Python Extension schon einmal verwendet.
Hierüber können sämtliche Pakete und Add-Ons für VS Code geladen werden können.
Darunter vor allem:
- Support für andere Programmiersprachen
- Erweiterungen um mit anderer Software zusammen zu arbeiten (z.B. Remote Server)
- Themes, die das Design ändern

Deshalb sieht auch das Visual Studio Code auf dem Screenshot wahrscheinlich etwas anders aus,
als die frisch installierte Version.
5 changes: 5 additions & 0 deletions hyperbook/book/entwicklung/python/index.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,5 @@
---
name: Python
index: 4
expanded: false
---
Binary file added hyperbook/public/images/python/download.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added hyperbook/public/images/python/socha-releases.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added hyperbook/public/images/python/vs-code.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.