Skip to content
This repository has been archived by the owner on Dec 26, 2023. It is now read-only.

Commit

Permalink
Merge pull request #16 from J-J-B-J/main
Browse files Browse the repository at this point in the history 
Update to main branch
  • Loading branch information
@J-J-B-J
J-J-B-J committed Nov 18, 2022
2 parents 0e1c9f6 + bd54aed commit 40db3e4
Show file tree
Hide file tree
Showing 5 changed files with 264 additions and 160 deletions.
2 changes: 1 addition & 1 deletion README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -24,5 +24,5 @@
</ul>

<p>
See our <a href="https://j-j-b-j.github.io/get-sentral/">official documentation</a> for more information.
See our <a href="https://j-j-b-j.github.io/get-sentral/">official documentation</a> or <a href="https://pypi.org/project/SentralTimetable/">PyPi page</a> for more information.
</p>
2 changes: 1 addition & 1 deletion SentralTimetable/scrapers.py
View file
Original file line number Diff line number Diff line change
Expand Up @@ -5,11 +5,11 @@
# Third party imports
from BarcodeGenerator import generate_barcode
from bs4 import BeautifulSoup
import datetime

# Local imports
from .objects import *


MONTHS_LONG = [
"",
"January", "February", "March", "April",
Expand Down
279 changes: 261 additions & 18 deletions docs/index.html
View file
Original file line number Diff line number Diff line change
Expand Up @@ -22,24 +22,6 @@
</div>

<ul class="navbar-nav ml-auto">
<li class="nav-item">
<div class="navbar-text"><a href="/get-sentral/installation">Installation</a></div>
</li>

<pre> </pre>

<li class="nav-item">
<div class="navbar-text"><a href="/get-sentral/variables">Variables</a></div>
</li>

<pre> </pre>

<li class="nav-item">
<div class="navbar-text"><a href="/get-sentral/usage">Usage</a></div>
</li>

<pre> </pre>

<li class="nav-item">
<div class="navbar-text">
<a class="github-button" href="https://github.com/J-J-B-J/get-sentral/subscription" data-size="large" data-color-scheme="no-preference: dark_high_contrast; light: dark_high_contrast; dark: dark_high_contrast;" data-icon="octicon-eye" data-show-count="true" aria-label="Watch J-J-B-J/get-sentral on GitHub">Watch</a>
Expand Down Expand Up @@ -379,10 +361,271 @@ <h5>
</p>
</div>
</div>
<<<<<<< HEAD
</div>

<br><br>


<h2>Installation</h2>

<div>
<h3>Download</h3>

<h5>Github</h5>
<ol>
<li>Download the <a class="link" href="https://github.com/J-J-B-J/get-sentral/archive/refs/heads/main.zip">latest source code</a>.</li>
<li>Unzip the file.</li>
</ol>

<h5>Github CLI</h5>
<small>N.B. Make sure you have the <a class="link" href="https://docs.github.com/en/github-cli">GitHub CLI</a> installed.</small>

<ol>
<li>Open a new terminal window/tab.</li>
<li>Change into the <code>Downloads</code> directory with <code>cd Downloads</code></li>
<li>Run <code>gh repo clone J-J-B-J/get-sentral</code> to download the files.</li>
</ol>

<h5>Github Desktop</h5>
<small>N.B. Make sure you have the <a class="link" href="https://docs.github.com/en/desktop">GitHub Desktop</a> installed.</small>

<ol>
<li>Open GitHub Desktop.</li>
<li>In the menu bar, click on <code>File > Clone Repository</code></li>
<li>Click on the URL tab.</li>
<li>Enter <code>J-J-B-J/get-sentral</code> into the <code>URL or username/repository</code> box.</li>
<li>Click <code>Choose...</code> to choose where to save the repo.</li>
<li>Set the clone name to <code>get-sentral</code> and the path to your <code>Downloads</code> folder.</li>
<li>Click select.</li>
<li>Click clone.</li>
</ol>
</div>

<div>
<h3>Build & Install</h3>
<small>
N.B. If you plan to use this as a library, then do this step.
If you plan to use it as a standalone program or on a micropython device, then skip this step.
</small>

<ol>
<li>Open a new terminal window/tab.</li>
<li>Run <code>cd Downloads/get-sentral</code> to enter the get-sentral directory.</li>
<li>
Run <code>python3 setup.py sdist bdist_wheel</code> to install the package.
<br>
<small>N.B. If you use Python 2, use <code>python</code> instead of <code>python3</code> above.</small>
</li>
<li>Run <code>cd dist</code> to enter the package directory.</li>
<li>Run <code>find . -type f -name "*.tar.gz"</code> to find the name of the package.</li>
<li>
Run <code>pip3 install [FILE_NAME]</code> to install the package.
<br>
<small>
N.B. FILE_NAME should be the result of the previous step's command.
So, if you got <code>./SentralTimetable-0.2.tar.gz</code>, then run <code>pip3 install SentralTimetable-0.2.tar.gz</code>
</small>
<br>
<small>N.B. If you use Python 2, use <code>pip</code> instead of <code>pip3</code> above.</small>
</li>
</ol>
</div>

<h2>Usage</h2>
<p>This page presumes you've installed the package and set the variables. See <a class="link" href="/get-sentral/installation">Installation</a> and <a class="link" href="/get-sentral/variables">Variables</a>.</p>

<div>
<h3>Standalone</h3>
<p>
This mode makes the program get your timetable and print out all the details, neatly formatted.
This method is NOT RECOMMENDED if you plan to use this program as a library or in a project.
Really the only time you should be using this mode is for testing.
</p>

<h5>Code editor</h5>
<ol>
<li>
Open the get-sentral directory in your favourite code editor, like <a class="link" href="https://www.jetbrains.com/pycharm/">PyCharm</a>.
<br>
<small>N.B. If you use a <a class="link" href="https://www.jetbrains.com">JetBrains</a> product, the project is already set up for you.</small>
</li>
<li>Run <code>example.py</code></li>
</ol>

<h5>Terminal</h5>
<ol>
<li>Open a new terminal tab/window.</li>
<li>Run <code>cd Downloads/get-sentral</code></li>
<li>
Run <code>python3 example.py</code>
<br>
<small>N.B. If you use Python 2, use <code>python</code> instead of <code>python3</code> above.</small>
</li>
</ol>
</div>

<br>

<div>
<h3>In an external Python program</h3>
<p>To use this mode, use:</p>
<pre>
<span class="pykey">import</span> SentralTimetable
SentralTimetable.get_timetable()</pre>
<p>Using <code>get_timetable()</code> returns the data as a <code>Sentral()</code> object. See the home page for details on this object, or see <code>objects.py</code>.</p>
<br>
<br>

</div>

<h2>Variables</h2>
<p>This page presumes you've installed the package. See <a class="link" href="/get-sentral/installation">Installation</a>.</p>

<p>The get-sentral program requires you to set some variables in order to get your timetable.</p>
<p>These include:</p>
<ul>
<li><code>USERNAME</code> - Your username</li>
<li><code>PASSWORD</code> - Your password</li>
<li>
<code>URL</code> - Your school's sentral url
<br>
<small>Make sure it starts with <code>https://</code> and ends with <code>/portal/dashboard</code></small>
</li>
<li><code>DEBUG</code> - Weather or not to debug the program</li>
<li><code>TIMEOUT</code> - The time to give the website to load before raising an error</li>
</ul>

<p>
You can set all of these variables in a number of different ways, or you can mix and match.
Please note that for some configurations of the program you may want to not use some settings.
See the 'Advantages & Disadvantages' section at the end to compare the mathods.
</p>

<div>
<h3>Parameters</h3>
<p>This is the simplest way of setting the variables. Simply pass them into the function, like so:</p>
<code>SentralTimetable.get_timetable(<span class="pyparam">usr</span>=<span class="pystr">"andy.griffiths1"</span>, <span class="pyparam">pwd</span>=<span class="pystr">"TerryIsAnIdiot"</span>, <span class="pyparam">url</span>=<span class="pystr">"https://yarravalleygrammar.sentral.com.au/portal/dashboard"</span>, <span class="pyparam">debug</span>=<span class="pykey">False</span>, <span class="pyparam">timeout</span>=<span class="pyint">5</span>)</code>
</div>

<br>

<div>
<h3>Environment Variables</h3>
<p>Set environment variables using one of the following:</p>
<ul>
<li><a class="link" href="https://www.schrodinger.com/kb/1842">Terminal</a></li>
<li><a class="link" href="https://www.jetbrains.com/help/pycharm/run-debug-configuration.html#run-debug-parameters">JetBrains apps</a></li>
<li><code><a class="link" href="https://docs.python.org/3.10/library/os.html#os.putenv">os.putenv()</a></code></li>
</ul>
<p>The environment variables are as follows:</p>
<ul>
<li><code><span class="pystr">"USER_NAME"</span></code></li>
<li><code><span class="pystr">"PASSWORD"</span></code></li>
<li><code><span class="pystr">"URL"</span></code></li>
<li>
<code><span class="pystr">"DEBUG"</span></code><small> - Set to <code><span class="pystr">"True"</span></code> or <code><span class="pystr">"False"</span></code></small>
</li>
<li>
<code><span class="pystr">"TIMEOUT"</span></code><small> - Set to an integer that has been formatted as a string, e.g. <code><span class="pystr">"15"</span></code></small>
</li>
</ul>

<p>For example, use the following code before calling <code>get_timetable()</code>:</p>
<pre>
os.putenv(<span class="pystr">"USER_NAME"</span>, <span class="pystr">"andy.griffiths1"</span>)
os.putenv(<span class="pystr">"PASSWORD"</span>, <span class="pystr">"TerryIsAnIdiot"</span>)
os.putenv(<span class="pystr">"URL"</span>, <span class="pystr">"https://yarravalleygrammar.sentral.com.au/portal/dashboard"</span>)
os.putenv(<span class="pystr">"DEBUG"</span>, <span class="pystr">"False"</span>)
os.putenv(<span class="pystr">"TIMEOUT"</span>, <span class="pystr">"15"</span>)</pre>
</div>

<br>

<div>
<h3>.json file</h3>
<p>This method uses a .json file to store a dictionary of credentials.</p>
<ol>
<li>Create a new file in the project directory called <code>Sentral_Details.json</code></li>
<li>Create a ditionary in the file using <code>{}</code></li>
<li>
Fill the dictionary with the following keys and values:
<ul>
<li><code><span class="pystr">"USERNAME"</span></code> - Your school username</li>
<li><code><span class="pystr">"PASSWORD"</span></code> - Your school password</li>
<li><code><span class="pystr">"URL"</span></code> - Your school's sentral url</li>
<li><code><span class="pystr">"DEBUG"</span></code> - Weather or not to debug the program - set to <code><span class="pykey">true</span></code> or <code><span class="pykey">false</span></code></li>
<li><code><span class="pystr">"TIMEOUT"</span></code> - Time to give the page to load before raising an error - set to an integer such as <code><span class="pyint">15</span></code></li>
</ul>
For example, set the contents of the .json file to:<br><br>
<pre>
{
<span class="pystr">"USERNAME"</span>: <span class="pystr">"andy.griffiths1"</span>,
<span class="pystr">"PASSWORD"</span>: <span class="pystr">"TerryIsAnIdiot"</span>,
<span class="pystr">"URL"</span>: <span class="pystr">"https://yarravalleygrammar.sentral.com.au/portal/dashboard"</span>,
<span class="pystr">"DEBUG"</span>: <span class="pykey">false</span>,
<span class="pystr">"TIMEOUT"</span>: <code><span class="pyint">15</span></code>
}</pre>
</li>
</ol>
</div>

<br>

<div>
<h3>input()</h3>
<p>If you do not enter the credentials in one of the above methods, the program will automatically ask for the credentials using the <code><span class="pyfn">input</span>()</code> function.</p>
</div>

<br>

<div>
<h3>Advantages & Disadvantages</h3>

<table style="width: 100%">
<thead>
<tr>
<th style="width: 25%" class="invisibletable">Method</th>
<th style="width: 25%" class="invisibletable">Changable from within program?</th>
<th style="width: 25%" class="invisibletable">Stored permanently?</th>
<th style="width: 25%" class="invisibletable">Hidden when committed?</th>
</tr>
</thead>
<tbody>
<tr>
<td style="width: 25%" class="invisibletable">Parameters</td>
<th style="width: 25%" class="invisibletable">✅</th>
<th style="width: 25%" class="invisibletable">❌</th>
<th style="width: 25%" class="invisibletable">❌</th>
</tr>
<tr>
<td style="width: 25%" class="invisibletable">Environment Variables</td>
<th style="width: 25%" class="invisibletable">✅</th>
<th style="width: 25%" class="invisibletable">✅<sup><small>1</small></sup></th>
<th style="width: 25%" class="invisibletable">✅<sup><small>2</small></sup></th>
</tr>
<tr>
<td style="width: 25%" class="invisibletable">.json file</td>
<th style="width: 25%" class="invisibletable">❌</th>
<th style="width: 25%" class="invisibletable">✅</th>
<th style="width: 25%" class="invisibletable">✅<sup><small>3</small></sup></th>
</tr>
<tr>
<td style="width: 25%" class="invisibletable">input()</td>
<th style="width: 25%" class="invisibletable">❌</th>
<th style="width: 25%" class="invisibletable">❌</th>
<th style="width: 25%" class="invisibletable">✅</th>
</tr>
</table>
<br>
<small>1: Only when using an environment or project file or similar.</small><br>
<small>2: Only when set from outside the program.</small><br>
<small>3: Only when added to the <code>.gitignore</code>.</small>
</div>

<br>
<br>

</div>
</body>
</html>
Loading

0 comments on commit 40db3e4

Please sign in to comment.