Metadata-Version: 2.1
Name: demo_package_python
Version: 0.0.19
Summary: This is a sample package which follows the instructions for publishing a Python package to PyPI.
Project-URL: Homepage, https://gitlab.com/demo-package/demo-package-python
Project-URL: Bug Tracker, https://github.com/demo-package/demo-package-python/~/issues
Author-email: "LJ. Sta. Ana" <lvjhn.mx@gmail.com>
License: Copyright 2022 Levi John Sta. Ana
        
        Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
        
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Requires-Python: >=3.7
Requires-Dist: bleach==5.0.1
Requires-Dist: build==0.8.0
Requires-Dist: certifi==2022.6.15
Requires-Dist: cffi==1.15.1
Requires-Dist: charset-normalizer==2.1.0
Requires-Dist: commonmark==0.9.1
Requires-Dist: cryptography==37.0.4
Requires-Dist: docutils==0.19
Requires-Dist: faker==13.15.0
Requires-Dist: idna==3.3
Requires-Dist: importlib-metadata==4.12.0
Requires-Dist: jeepney==0.8.0
Requires-Dist: keyring==23.6.0
Requires-Dist: packaging==21.3
Requires-Dist: pep517==0.12.0
Requires-Dist: pkginfo==1.8.3
Requires-Dist: pycparser==2.21
Requires-Dist: pygments==2.12.0
Requires-Dist: pyparsing==3.0.9
Requires-Dist: python-dateutil==2.8.2
Requires-Dist: readme-renderer==35.0
Requires-Dist: requests-toolbelt==0.9.1
Requires-Dist: requests==2.28.1
Requires-Dist: rfc3986==2.0.0
Requires-Dist: rich==12.4.4
Requires-Dist: secretstorage==3.3.2
Requires-Dist: six==1.16.0
Requires-Dist: toml==0.10.2
Requires-Dist: tomli==2.0.1
Requires-Dist: twine==4.0.1
Requires-Dist: urllib3==1.26.10
Requires-Dist: webencodings==0.5.1
Requires-Dist: zipp==3.8.0
Description-Content-Type: text/markdown

# DEMO-PACKAGE-PYTHON 
This sample package follows the instructions 
for publishing a Python package in PyPI. 

This repository can be used as a template for building packages. 
See section `Reusing as Template` for more info on how.

## Outline 
This `README.md` file is organized as follows: 

1. Outline 
2. Full Instructions 
3. Summarized/Compact Instructions
4. Code Structure 
5. Demo Package Installation Instructions
6. Reusing as Template
7. Adding Additional Files

## Full Instructions 
Full instructions for publishing a Python package using 
PyPI can be found here: 
https://packaging.python.org/en/latest/tutorials/packaging-projects/

I made a `tinyurl.com` short-link for the 
tutorial link above:

https://tinyurl.com/how-to-package-python

If you want, you can include the links above in your bookmarks.

## Summarized/Compact Instructions 
In summary, the instructions can be divided into the outline below
if you don't feel like clicking the tutorial link again and again.

Full instructions can be found in the tutorials above in case 
the summary doesn't still help in recalling the procedures.

1. Creating a package 
    1. Create package files (see code structure below for an example)
    1. Create `tests/` directory
    1. Create `pyproject.toml` with the necessary `[build-system]`, `[project]`, and `[project.urls]` options
    1. Configure metadata of project. Common metadata are shown below. For a more thorough example, see `pyproject.toml`
        1. name 
        1. version
        1. authors (must be in array format)
        1. description 
        1. readme
        1. license
        1. requires-python
        1. classifiers
    1. Create `README.md` file
    1. Create `LICENSE` file
1. Generating distribution archives 
    1. Step 1: Install `build` package 
    ```
    python3 -m pip install --upgrade build`
    ``` 
    1. Step 2: Run `python3 -m build` on the first build and successive build updates for different versions.
        * Generates a `dist/` folder for the built package
        * Puts a `.whl` and `.tar.gz` file in the dist folder for the current version.
1. Uploading the distribution archives 
    1. Install `twine`, a tool for uploading packages to different package indices. 
        ```
        python3 -m pip install --upgrade twine
        ```
    1. Upload archives under `dist`
        ```
        python3 -m twine upload --repository testpypi dist/*
        ```


## Code Structure 

```bash
demo-package-python
    dist/                           # distribution files 
    env/                            # virtual environment for the package 
    scripts/                        # scripts 
        build_pyproject_toml.py     # build pyproject_toml.py 
    src/                            # source files for the package 
    tests/                          # tests for the package 
        main.py         
    utils/  
        build.sh                    # shell script for building package
        publish.sh                  # shell script for publishing package
        setup.sh                    # shell script for setting up package
    LICENSE                         # MIT License 
    pyproject.dev.toml              # project configuration 
    pyproject.toml                  # built project configuration
    requirements.txt                # requirements list generated by pip freeze
```

## Demo Package Installation Instructions
The demo package has a simple API of 3 functions. 

* `.say_hello_world()`
* `.say_hi(name)`
* `.random_rainbow_color()` - uses the `faker` package 

To use this package: 
`pip install demo_package_python`

Then: 
```js
import demo_package_python as demo_package

print(".sayHello() => " + demo_package.say_hello_world()) 
print(".sayHi('John') => " + demo_package.say_hi('John'))
print(".randomRainbowColor() => " + demo_package.random_rainbow_color())
```
It should return the following: 
```
.say_hello() => Hello, World! 
.say_hi('John') => Hi, John!
.random_rainbow_color() => blue
```

## Reusing as Template
If you intend to reuse this package as a template for future package projects, use the following command: 

1. `git clone https://gitlab.com/demo-package/demo-package-python.git`

1. Edit `pyproject.dev.toml` to match your project description. 
    > Make sure to edit the right file, you might accidentally 
      edit `pyproject.toml` instead. 

    > The file `pyproject.toml` is 
      automatically built from `pyproject.dev.toml` by adding the dependencies list 
      in `requirements.txt` before building.  

1. Remove contents of `src/demo_package_python`  
    ```
    rm -rf src/demo_package_python/*
    ```

1. Create `__init__.py` in `src/demo_package_python`
    ```
    touch src/demo_package_python/__init__.py
    ```

1. Rename `src/demo_package_python` to `src/[your_project_name]` 
    ```
    mv src/demo_package_python src/[your_package_name]
    ```
1. Make sure that your have `virtualenv` installed and then run the following
    ```
        virtualenv env 
    ```
    or 
    ```
        python3 -m venv env
    ```

1. Activate virtual environment
    ```
        source env/bin/activate
    ``` 

1. Run from the command line:
    ```
    bash utils/setup.sh
    ```

1. Use the following commands to simplify routines: 
    1. `bash utils/build.sh` - to build project (make sure to update `project.version` in `pyproject.dev.toml` before building)
    1. `bash utils/publish.sh` - to upload the project
