DEV Community: Marco Pasqua

Releasing my First Tachiyomi Contribution

Marco Pasqua — Fri, 05 Jan 2024 01:46:15 +0000

Hi everyone, if you've been reading my blog posts about Tachiyomi, then you would have known that in my last blog post I created a pull request for the issue I was working on for Tachiyomi's website. All I had to do was wait for the repo owner to accept or request a change to the contribution I made. Well, they got back to me and did request a few changes to make things clearer.

What Changes were Requested

These are the two requests:

The first request
The second request

As you can see from the links, they're both very simple changes that I had to make.

Working on the Requested Changes

After I read through the requests, and asked a question to clear up some confusion on the first request. I got to work on updating my contribution to match them. I continued my work in the same branch from my previous contribution and once I as done, I committed it. The repo owner, then accepted my contribution and had it merged with the website. You can see this change right now on their website right now. I enjoyed working on this contribution and I'm looking forward to perhaps continuing to contribute to Tachiyomi in the future.

What About the Android App?

If you recall I was also working on an issue for their Android app. Unfortunately, I wasn't able to get past the previous issue I faced, which was the duplicate description from when the Markdown function was used. The repo owner did tell me what I would have to update for it to properly work, but I unfortunately had a hard time trying to do so, I didn't really understand how I would write out in the code. I tried looking it up, but couldn't find much. I did also look at how the developers used the Markdown function in their own code, and tried replicating it but with no success. I think that this was probably due to me still not knowing enough about Kotlin and how it works. So unfortunately, this was an issue that I was not able to complete. I'm hoping that maybe in the future, once I've used Kotlin enough and become familiar with it I can create a contribution for the issue. But for now this is something that I wasn't able to complete and will require a lot more practice than I anticipated, as I bit off more than I could chew.

Overall

Moving past the unfortunate news, I'm glad that at I have a couple things that I could take away from this. The most notable being that I now have a general knowledge of Kotlin now, one which I for sure have to practice more with. I also was able to make a small contribution to Tachiyomi, which is certainly a start to what I initially planned to do with Tachiyomi.

So for now, I'll end it off here. I appreciate you all for following my Tachiyomi contribution journey, and I'll catch you all in the next blog post.

Working on My First Tachiyomi Contribution

Marco Pasqua — Fri, 05 Jan 2024 01:29:19 +0000

Hi everyone, if you've seen my previous blog post, you would have read about my plans to make my first two contributions to Tachiyomi. In short, I had to update the documentation of their website to state that 1 EPUB file = 1 chapter. As well as make sure that the description of a series supported Markdown, which you can find here.

Working on the Website Issue

As I mention in my planning phase, I asked a contributor where this change should be made. Well, he responded and showed me where this change should be made, which is here. So I got to work. I first, forked the repo, then cloned it to my computer. After that I opened it on VS Code and in my command line, I created a branch for this issue. I then made the documentation changes required. I ended up doing this below the part of the page where supported file formats are mentioned. After I wrote the change, I read it over to make sure it sounded right, and created a pull request. Now I just have to wait for any changes requested by the repo owner.

Working on the Android App Issue

If you remember in my previous blog post, I mentioned how for this issue I would have to learn Kotlin. Well, I did end up learning it and to be honest Kotlin, doesn't seem too hard. I actually enjoyed learning it, I like how its syntax is deferent from Java;

Java functions are created like this, private String name(), whereas Kotlin creates them like so, fun name(): String. Also, printing is different. Java is System.out.println() and Kotlin is simply println(). There is much less that you have to type with Kotlin, and I like it.

I also like that you can create extension functions in Kotlin.

After I learn Kotlin and created a few test apps modeled after code I made in my Android Java development class, I left a comment on the issue expressing my interest in working on it and which file I must work in. This prompted for the repo owner to reply and tell me where this change must be done. Which resulted in me creating a fork, cloning it, and making a branch for it. The repo owner also told me about a open source Markdown converter that they use for a similar feature in the app, which is displaying updates for their app.

I did a few test with the function, and tried my own thing. I actually managed to get the links to display on the description of the manga/comic, which meant that it was parsing the Markdown correctly. However, these links were clickable, and someone commented saying that we should make them unclickable as we shouldn't be trusting links from websites. This was something that I agreed with, and then looked at how I can remove the hyperlink. I found out that I can simply use the comment syntax  for HTML to remove the hyperlink. All I had to do was insert the start and the end of the comment between the [ and ] of the link. I was able to do this using Regex, so I had it figured out on that end.

However, there was one problem. The Markdown function was returning null with the text, which it shouldn't be doing. I asked a question about it, and was told that I was using the function incorrectly. I then realized that I was using the wrong function altogether. I double checked the file where they use the markdown function and made this realization. So for now, I'm trying to use the function correctly, and while I see that it does parse the description, it produces a duplicate of the description. So this is something that I'll have to figure out for the next blog post.

So for now, that concludes this blog post. Thanks for reading, and I'll see in you in the next one.

Planning my First Tachiyomi Contribution

Marco Pasqua — Fri, 05 Jan 2024 01:14:36 +0000

Hi everyone, if you've been following me for a while you may know that I use a comic/manga reader on my phone called Tachiyomi. I've been wanting to contribute to this project for a while and started looking at open issues that might be good for a first timer like me. So I did some searching between the repos used for their Android App and their Website. I eventually settled for two issues, this [issue] here (https://github.com/tachiyomiorg/website/issues/1093) that I found on the repo meant for their website. As well as an issue I found on the repo for their Android app. I'll talk about them below.

What's the Issue on their Website?

This website issue is fairly simple. It's really just making a minor update to their website's documentation. The update that I have to make is in regards to how the app processes locally read files. In short, the app will count the number of files in a folder for a series. Each file is counted as a chapter. However, for a file type, such as EPUB, where all of the chapters are usually in one file. The app is unable to count each chapter, unless the EPUB is broken up into separate files for each chapter of the book/series. So this must be documented on their website.

What's the Issue for their Android App

The issue for their Android App seems somewhat simple, essentially I have to make sure that the description of a manga/comic is able to support Markdown. So I really just have to make, sure that things like links, bolds, or italics are properly displayed on the screen for the user to see. Whereas they previously were not being displayed correctly. For example, a link would look like this [link](www.example.com) meanwhile it should look like this link. As you may know, I worked on creating a Python Application that converts Markdown into HTML. So I figured that with my previous Android knowledge with Java, I could learn Android development with Kotlin and tackle this issue. Since there shouldn't be too many differences between Android development with Java and Kotlin.

What's the Plan for the Website?

As I said before, this is a fairly simple issue, and kind of serves as a small introduction to contributing to Tachiyomi. So my plan is to ask one of the contributors were this change should be made, and then make a fork of the repo, clone it and create a branch for the issue. This seems fairly straight forward, and shouldn't take too long.

What's the Plan for the Android App?

To tackle this issue, I'm going to try learning Kotlin, which I think should be pretty easy to pick up considering that it isn't too different from Java. To learn it, I'll split it up into two different parts. I'll first learn some of the features, and syntax differences between Java and Kotlin. Then I'll try to create an app or two with Kotlin that should function the same as the Java versions that I created for assignments in class. This should probably take a day or two. After that, I'll leave a comment on the issue saying I'd like to work on this, and ask which file the related code is located in. Then, I can just fork it, clone and create a branch to work on it, and hopefully things go smooth.

So I'll get to work on this and see you guys in the post talking about my progress. Thanks for reading!

Releasing my First Open Source Project

Marco Pasqua — Sun, 03 Dec 2023 02:03:58 +0000

Hi everyone, if you've been following my blog posts for a while, you may know that I have been working on an open source project called TXT to HTML Converter. Well, I recently released it. You can find it here, on PyPI. I'll talk about the release process below.

What Platform did I use to Release my project

As mentioned above, I used PyPI. PyPI is a service used to host packages or projects made by you. It's used by open source projects like Black.

What was the Release Process Like?

The release process was a little bit complicated for me, as I originally had a hard time with having it run on PC. I'll talk about part of the setup process below, to hopefully help out others releasing their first project on PyPI.

PyPI provides a tutorial that you can use when you're getting ready to release a package. I based majority of the setup process off of this tutorial. I created a new file called __init__.py. I also moved all of my source code, including __init__.py, into a folder that has the name of my package. I left __init__.py empty. I also made changes to my toml file called pyproject.toml. As you may know, I've used this toml file to configure my formatter, Black, and linter, Ruff. Now I'm also using it to configure the release of my package, I'll show what the file looks like for me.

[build-system]
requires = ["hatchling"]
build-backend = "hatchling.build"

[project]
name = "text-to-html-converter"
version = "1.0.2"
authors = [
  { name="Marco Pasqua", email="email@gmail.com" },
]
description = "A package that allows for txt and md conversion to HTML files."
readme = "README.md"
requires-python = ">=3.11"
classifiers = [
    "Programming Language :: Python :: 3",
    "License :: OSI Approved :: MIT License",
    "Operating System :: OS Independent",
]

[project.urls]
Homepage = "https://github.com/Pasqua101/txt-to-HTML-converter"
Issues = "https://github.com/Pasqua101/txt-to-HTML-converter/issues"

PyPI provides a good explanation in their tutorial. However, I'll explain some of the things I did. While most of it is self-explanatory, you can see that I've stated that my program requires Python 3.11 and above. This is due to a library I used called TOMLlib, which is built into Python 3.11 and above. You can also see that I've provided a version number, which I can update for each release, as well as a description. The build system part is something that is necessary for uploading the package to PyPI. Other than that, I did make changes to my import statements. Instead of doing something like from helper import extension_checker, my imports now looked like this from . import helper as h. According to my peer, I had to do this to get my code to be able to work with PyPI. Even if it didn't work on my computer in the end. Moving on, when I did all that, I then made sure to set my PyPI token. The tutorial should mention how to get and use this token for releasing your package. Afterwards, I ran this command python -m build. This command builds my program, and puts the required files to be uploaded in a dist folder. To upload the dist files, I first had to install Twine by doing this python -m pip install --upgrade twine. I was then ready to upload it with this command py -m twine upload --repository pypi dist/*. This is where the token comes into play. The token is able to create a project on my account for the files to be hosted and downloaded from as a package. If I needed to fix my code, I could make my changes, then change the version number in the pyproject.toml file and run the same upload command from earlier.

Testing my Package

I had a peer testing my work, who also helped me solve most of the problem with my code not being able to run. They seemed to have no problems with running my package, during the testing phase. However, I did notice that since I moved my source code into a new folder, I had to make some changes to my testers. This is something that I set as an issue for myself on my repo.

How to Install my Program

To install my program, you can navigate to this link that it's hosted at. Here, you can choose to learn more about it, or run this command, pip install text-to-html-converter, to get started. Once the package is installed, you should then be able to run it like so python -m text-to-html.text_to_html -h. This will display some information about the app, and how to use it. After that, you're all set! Enjoy using my program and feel free to report any bugs or problems you come across by going to my repo.

Thank you all for following my journey of creating and publishing this program! I hope it has some use to you all, despite the simple problem it accomplishes. See you in the next blog post.

Reinforcing my ReactJS Knowledge

Marco Pasqua — Sat, 25 Nov 2023 04:54:08 +0000

Hi everyone, this should be a much shorter post, but I just want to talk about the recent contribution I made to the Calculator for Everything repo. This contribution is very much like the one I made in my last blog post titled, Expanding on My ReactJS Knowledge. So most of this blog post won't be as detailed as the previous one. However, I'll talk about what I did below.

What was the Issue I Worked on?

The issue I created was to update another calculator that I made for the repo. The difference being that this time instead of updating my momentum calculator, I was updating the density calculator that I made for Hacktoberfest.

Going into this issue, I already knew what had to be done. I had to create a dropdown menu using the <InputLabel>, <Select> and <MenuItem> tags. As well as a new functions and variables to track the selected unit of measurement for both mass and volume. If you are interested in having a more comprehensive explanation of what I did, I highly suggest that you read my previous blog post. Since this contribution and the previous one as pretty much identical. That being said, I will briefly describe how I used these tags with the example below.

<InputLabel style={{ position: 'absolute', top: -20 }}>Unit</InputLabel>
<Select
label="Mass Unit"
value={massUnit}
onChange={handleMassUnitChange}
fullWidth
>
    <MenuItem value="kg">Kilograms (kg)</MenuItem>
    <MenuItem value="g">Grams (g)</MenuItem>
    <MenuItem value="mg">Milligram (mg)</MenuItem>
    <MenuItem value="oz">Ounces (oz)</MenuItem>
    <MenuItem value="lb">Pounds (lb)</MenuItem>
    <MenuItem value="t">Metric Tons (t)</MenuItem>
</Select>

As you can see above, I used <InputLabel> to name the menu, While I used <Select> to create it, and <MenuItem> to give the menu options. With this, I was able to use the onChange={handleMassUnitChange} to track the unit of measurement selected by the user. I also had a similar setup for my volume. This would allow me to then convert the provided input back into kilograms (kg) or cubic meters (m³).

After I created the menu, and updated my functions to support converting mass and volume back to kg and m³. I got to testing my code. To do this, I compared my results with an online calculator. I saw that the results were the same, which allowed me to push this and create a pull request (pr) on the repo. This pr was tested by the continuous integration (ci) set up by the owner, which basically made sure my code would work when deployed and there were no errors. If you would like a more in depth explanation of the ci, I would suggest to read my previous blog post. Moving on, my code passed these tests just fine, and it allowed for the repo owner to merge it. This contribution allowed me to reinforce some of my ReactJS knowledge, as well as test my memory on how drop down menus are made.

The Honest Truth

There is something I must tell you about my actual plans for this blog post. Truth is, I didn't really plan on contributing to this repo again. I did some searching yesterday and came across this really interesting repo called OpenComic. OpenComic is essentially a JavaScript app designed to run on your computer to read comics, manga and graphic novels. I was actually thrilled by the idea of contributing to this repo, because if you remember from some older blog posts, I use an open source Android app called Tachiyomi which works in a similar way, except instead of just reading the files locally, it also pulls them from websites. I thought that by contributing to this I may have a good start on contributing to Tachiyomi in the future, despite me not knowing Kotlin.

Moving back to OpenComic, I came across an issue created by a Mac user. Basically, when a Mac user would go the about section of the app, it would open an alert window with no buttons to close the window causing the user to be stuck on the screen. This seemed like a pretty easy bug fix, as I have had experience with alerts in both JavaFx and Java for Android so I was expecting it to be similar for JavaScript. My main idea was to create the buttons to close a window, instead of the 'x' that would be present at the top of it, like in most OSs. I had this idea, because since I'm not a Mac user there's no actual way for me to be 100% sure that on Mac the x button would appear above the alert window. With this idea in mind, I left a comment on the issue. While I did see that this was already self-assigned to the repo owner, I also saw a lot of other issues that were self-assigned. So I was hoping that I could lighten the load for the owner. Unfortunately, when the owner responded to me, they said that they already took care of the issue. Fortunately for me, they said that this feature would be in the next beta version of the app, and invited me to test it and make sure it was working. At the time of writing this, that beta version has already been released. So I might try to go through it and see if I can find any bugs.

Anyways, that is the honest truth, I was hoping that I could have had the chance to contribute to OpenComic instead of to Calculator for Everything.

What's my Plan Moving Forward?

Moving forward, I'm planning to potentially test the OpenComic
v1.0.0-beta.5 and see if I can spot any bugs. If I don't find any bugs then I'll take a look at the issues that occasionally come into the repo. That's not all, I'm also planning to teach myself the basics of Kotlin in the coming days. I'm hoping that with my Android development experience in Java, I can quickly grasp the fundamentals of Kotlin Android development and possibly make my first ever contribution to Tachiyomi.

That concludes my blog post for now. Thank you to everyone who continues to read and follow my story through the open source world. I'll catch you all in the next post, where I possibly make my first release of my Text to HTML Converter! Take care!

Expanding on My ReactJS Knowledge

Marco Pasqua — Thu, 23 Nov 2023 22:48:53 +0000

Hi everyone, I recently expanded on my ReactJS knowledge through a contribution I made to a repo called Calculator for Everything. Some of you may know about this repo through my previous HacktoberFest contribution blogs. I won't cover majority of what I did in those contributions. So if you're interested in learning about those contributions, you can read my blog posts Second PR of Hacktoberfest and Last PR of Hacktoberfest, which talk about this repo.

Anyways, the contribution I made to the repo this time was to expand on the Momentum Calculator I made in a previous issue. In that issue, I created a calculator to solve for Momentum, using mass and velocity. However, in that contribution, mass and velocity were only using one unit of measurement, which was kilograms (kg) for mass and meters per second (m/s) for velocity. I wanted to expand on this so it could use more than one unit of measurement for mass and velocity.

To start, I created an issue on the repo stating the changes I would like to make. Once it got approved by the repo owner I got to work. I'll talk about it below.

Working on the Issue

In the issue I mentioned the idea I had to get this working. I wanted to created a dropdown menu that would allow for the user to select from a list of different units of measurement for both mass and velocity. I already had a general idea of how this could work, thanks to previous applications I made with JavaFX and for Android using FXML. However, for both methods were different. For JavaFX to make a dropdown, I have to use the combobox UI element, whereas for Android development with Java I had to use the Spinner tag in an XML file. With ReactJS, this method was also different. After doing some research I found out that in order to make a dropdown menu, I would have to do something like this in the area of my code where I wanted the menu.

<InputLabel style={{ position: 'absolute', top: -20 }}>Unit</InputLabel>
<Select
label="Mass Unit"
value={massUnit}
onChange={handleMassUnitChange}
fullWidth
>
<MenuItem value="kg">Kilograms</MenuItem>
<MenuItem value="g">Grams</MenuItem>
<MenuItem value="oz">Ounces</MenuItem>
<MenuItem value="lb">Pounds</MenuItem>
</Select>

Looking at the code it's pretty easy to see how the dropdown menu is made from a UI perspective. If I wanted to label the menu, I can use <InputLabel> to give a title to the menu, and then use the style attribute to position the label. To create the actual menu, I had to use the <Select> tag. Here I can assign it a label, and a value. I'll talk about the onChange attribute in a bit. After that, I could then populate the inside of the tag with the <MenuItem> tag. From here, I could assign each <MenuItem> tag with a value that is respective to the text/option in the tag. As you can see above, for the Grams option, I have assigned it the value "g". This brings me to the onChange attribute in my <Select> tag. The onChange attribute is linked to a function I created in my code called handleMassUnitChange. This function is used only when the user selects an option from the menu, and affects the useState value set for the massUnit variable, which changes the unit of measurement being used. By default this value is set to "kg", but if grams was selected it would then switch to "g". This affects the way the value entered for the mass is used and I have a similar method for the velocity.

Since the unit of measurement used for Momentum is kg m/s, I would need to make sure that the measurement selected for both mass and velocity gets converted back to kg and m/s. This is where something like my convertMass and convertVelocity functions come into play. When the user clicks the button to solve the equation, it will run the functions that check the unit of measurement being used for both variables and convert their values to kg and m/s which I then multiply to solve for the momentum. I tested this out a few times, and compared it to an actual Momentum calculator online. After verifying the product I received for momentum with my calculator and compared it to the one I found online, I saw that the results were the same. This was a good sign for me, so I moved onto the second last step.

The second last step, I had to accomplish was to update the info file for the calculator. The changes I had to make were very simple. I just had to state the new units of measurement that both Mass and Velocity would use. This brought me to the final step.

Lastly, I just had to push my contributions to my fork and create a pull request for the changes I made. As you may remember in my previous contributions to this repo, the owner has setup a template for all contributors. I followed the template and then sent in my request. After I created the request, I noticed something new. The repo owner has implemented continuous integration into contributions made to their repo. This was done to not only test my code for deployment to their website, but to detect and fix vulnerabilities in my contribution. I actually found this to be really interesting, this application they used for this is called GitGuardian, if you wanted to check it out. I think I should learn more about it, and see if it's something I would like to use in future products.

Overall

This contribution is meant to be a step up from my previous Hacktoberfest contributions, and while it was as I did learn more about ReactJS. I knew I could do better to improve. However, for now this isn't that bad of a step up. Since I did have a take away, which was learning dropdown menus in React and using that to improve old code. I'm hoping that for my next contribution I can help out a larger repo. I did have that in mind for this contribution, but most repos that interested me where for languages I have little to no knowledge of, and for the repos I was interested in when I tried to clone it and run it locally I had a hard time installing certain prerequisites. Hopefully for a future contribution, I can change this and actually make a more significant contribution as that was my original goal for one of my Hacktoberfest contributions.

Anyways, that concludes this blog post for now. Once again thank you all for reading. I also noticed that I recently gained quite a few new followers. Thank you for following me and watching my journey to improve my coding abilities. I'll catch you all in the next post!

Using GitHub Actions with my Project

Marco Pasqua — Fri, 17 Nov 2023 03:29:11 +0000

Hi everyone, I recently had the chance to integrate a CI workflow into TXT to HTML Converter project. I'll talk about it below.

What was the Set up Process Like?

Setting up the workflow for my project was very simple. I followed the steps from the tutorial posted by GitHub and basically created a workflow to test my project. GitHub created template for me, and the directories to store the YAML file in.

What Does my Workflow Look Like?

After the YAML file was created, I continued to follow GitHub's tutorial. It was very simple and direct, it told me how I can run my code on different versions of Python as well as different OSs. Here is the YAML file I used that tests with different Python versions and OSs.

# This workflow will install Python dependencies, run tests and lint with a single version of Python
# For more information see: https://docs.github.com/en/actions/automating-builds-and-tests/building-and-testing-python

name: Python application

on:
  push:
    branches: [ "main" ]
  pull_request:
    branches: [ "main" ]

permissions:
  contents: read

jobs:
  build:

    runs-on: ${{ matrix.os }}
    strategy:
      matrix:
        python-version: ["3.11", "3.12"]
        os: [windows-latest]

    steps:
    - name: Checkout code
      uses: actions/checkout@v2
    - name: Set up Python ${{ matrix.python-version }}
      uses: actions/setup-python@v2
      with:
        python-version: ${{ matrix.python-version }}
    - name: Install dependencies
      run: |
        python -m pip install --upgrade pip
        pip install ruff
    - name: Lint with Ruff
      run: |
        ruff --output-format-github .
      continue-on-error: true

    - name: Test with unittest
      run: |
        python -m unittest discover tests

Thankfully, my project has no dependencies so I don't have to make pip install anything other than Ruff to lint my code, which you can see above. I only make my program run the testers with two versions of Python, 3.11 and 3.12. I chose these versions in particular because there is a library my program uses called tomllib. Tomllib is built into Python 3.11 and above, which means that my program does not support 3.10 and below. So I've only made it test with the two most recent versions of Python. I also wanted to attempt running my program on different OSs, like Ubuntu and MacOS, but I believe way those two OSs handle file paths differently from Windows. So when I was trying to handle file paths, it was expecting it in the Windows way and not the Linux way. So for now, it looks like my program does not work with Linux and MacOS. That concludes what I did for my workflow, next I'll talk about writing a test for a peer's program.

Writing a Test for a Peer's Program

I made a contribution to my peer's program called Waypoint. I made a contribution to their testers. The way they had it setup was different from mine. I had my program store all the testers in a tests folder for organizational reasons. I also split up the testers for each file, for example my testers for my helpers.py would have its own tester file. While my peer combined all their testers into one file. However, we both used unittest so I could just look at their code and jump right into creating a unittest. Thanks to my prior knowledge of making unittests for my program, this was simple. I created a tester to test the output of the function that handles Markdown conversion. I tested it, then committed and then made a PR. The tester worked with the CI my peer made and so they merged it. This leads me to my final thoughts about CI.

What do I think of CI?

I think that CI is a pretty handy tool for development, and I found the setup process to be really simple (for Python at least). I liked how I can use it to test my PRs on GitHub to make sure that the code I'm contributing works issue free. I also think that if I were to make another project, I would use CI in it. So, I'm definitely looking forward to how I can use it more in my programs, and what I can take advantage of to help me.

That's all for now. As always thank you for reading, and I'll catch you all in the next blog post.

Testing Python Code Using UnitTest

Marco Pasqua — Thu, 09 Nov 2023 18:49:30 +0000

Hey everyone, I recently had to create testers for my TXT to HTML Converter program. To do this I used the built-in UnitTest framework, which I'll talk about below.

Why did I Choose the UnitTest Library?

Like I said above, I chose the UnitTest framework because it is built into Python, which should make things easier for contributors as it reduces the number of libraries they need to install in order to get started on the program. I also have a little experience with reading the syntax for the library due to a Data Structures and Algorithms class I took in a previous semester, where my professor had us write data structures and algorithms in Python which we had to test with testers they wrote with the UnitTest framework.

Aside from that the UnitTest framework is quite simple to understand and works very well with my IDE, PyCharm, since I can run the tests in the IDE without having to use the command-line. I'll talk about the setup and how I got them to work with my program next

Using UnitTest with my Program

To set up the framke work, I had to import the unit test library into a python file that starts with test_, as well as the function you want to test. Then you must define a class that uses unittest.TestCase and create a function in the class that also has the test_ prefix. To better explain it, I'll show a brief example below for a function I have that returns true or false based on the file extension.

import unittest

from helper import extension_checker


class TestExtensionChecker(unittest.TestCase):
    def test_extension_checker_txt(self):
        result = extension_checker("1.txt")
        self.assertTrue(result)

        result = extension_checker("1.md")
        self.assertTrue(result)

        result = extension_checker("1.html")
        self.assertFalse(result)


if __name__ == "__main__":
    unittest.main()

Using self.assertTrue or False allows the tester to make sure that the return value is what it is supposed to be. There is also self.assertEqual which you can use to directly compare the return value with a string or another value. An example is provided below;

class TestMarkdown(unittest.TestCase):
    def test_convert_bold(self):
        converted_string = parse_md("**Hello World**")
        self.assertEqual(converted_string, "<strong>Hello World</strong>")

    def test_convert_hr(self):
        converted_string = parse_md("---")
        self.assertEqual(converted_string, "<hr>")

    def test_convert_link(self):
        converted_string = parse_md("[YouTube](https://www.youtube.com/)")
        self.assertEqual(
            converted_string, "<a href=https://www.youtube.com/>YouTube</a>"
        )

    # Tests conversion result for both 1 and 3 backticks
    def test_convert_code(self):

        converted_string = parse_md("`\``Hello world`\``")
        # Note: In my actual code the backslash isn't in the string. 
        # I did this to prevent Markdown from reading "Hello world" as another code block.

        self.assertEqual(converted_string, "<code>Hello world</code>")

        converted_string = parse_md("`Hello world`")
        self.assertEqual(converted_string, "<code>Hello world</code>")

It was with this test that I made that I was able to test my parse_md function, previously called check_md_and_write, and locate a bug that I uncovered a last week. I noticed this bug when I was using the linter, Ruff, and formatter, Black, I set up for my project. If you're interested in reading about the linter and formatter I chose and the setup process you can read last week's blog. Essentially the problem was that I could not parse any Markdown in my program. I wasn't sure what the problem was, but I think it had something to do with when I refactored my code and tried to clean things up. Luckily, I still has the branches where I worked on improved the function to parse markdown and the refactoring branch. To make note of it, I made an issue for myself and specified which branches to take a look at.

To fix the solution I compared the code I had with the branch I made for issue-16 since this had the completed version of my function, just without the refactoring changes. I ended up falling back on this function and changed the way it gets called. Which was by checking if the file had the md extension before entering the function, whereas before I would enter the function and then check if it was an md file. I did this because when I ran the tester I noticed that it would not return anything, so I suspected that it wasn't able to check the file extension and would return nothing as a result. This change worked and got the function working properly again. I made sure to commit this just in case, I messed up the function again in the future.

The next tester I made was for my main program logic. This one was a little more complex for me, as I was initially stuck on how to use it and thought I had to make mock files and folders to get it work. However, it was simpler than I thought. Unittest has two functions that worked for my program, called setUp and tearDown. setUp is called before the test is executed and is meant to prepare the test call for the test function. tearDown is called once the test ends and cleans up any files or folders that were made from the test. Using these two functions I was able to build this test to test the result of txt to html conversion;

import os
import tempfile
import unittest

from file_processors import text_to_html

class TestTextToHtmlTxtConversion(unittest.TestCase):
    def setUp(self):
        # Creating a temporary input file with some text content
        self.input_file = tempfile.NamedTemporaryFile(
            mode="w", suffix=".txt", delete=False
        )
        self.input_file.write("This is a test file.\n")
        self.input_file.close()

        # Creating a temporary output directory
        self.output_dir = tempfile.TemporaryDirectory()

        # Defining the stylesheet, language, and sidebar
        self.stylesheet = "https://cdn.jsdelivr.net/npm/water.css@2/out/water.css"
        self.lang = "en-CA"
        self.sidebar = None

    def tearDown(self):
        # Deleting the temporary input file and output directory
        os.remove(self.input_file.name)
        self.output_dir.cleanup()

 def test_text_to_html_txt_conversion(self):
        with self.assertRaises(SystemExit) as cm:
            # Calling the text_to_html function and store the HTML content
            html_content = text_to_html(
                self.input_file.name,
                self.stylesheet,
                self.output_dir.name,
                self.lang,
                self.sidebar,
            )

            self.assertEqual(cm.exception.code, 0)

            # Defining the expected HTML content
            expected_html_content = (
                f"<!DOCTYPE html>\n"
                f'<html lang="{self.lang}">\n'
                f"\t<head>\n"
                f"\t\t<meta charset='utf-8'>\n"
                f"\t\t<title>This is a test file</title>\n"
                f"\t\t<meta name='viewport' content='width=device-width, initial-scale=1'>\n"
                f'\t\t<link rel="stylesheet" type="text/css" href="{self.stylesheet}">\n'
                f"\t</head>\n"
                f"\t<body>\n"
                f"\t\t<p> This is a test file.</p>\n"
                f"\t</body>\n"
                f"</html>"
            )

            # Check if the HTML content matches the expected HTML content
            self.assertEqual(html_content, expected_html_content)

if __name__ == "__main__":
    unittest.main()

You can see that in the setUp function I prepare the variables and files that will be used in the text_to_html function, and in tearDown I make sure to remove the temp file and folder that were made in setUp. Also, since I've created my program to exit with a code of 0 when successfully executed I had to wrap the entire test function in with self.assertRaises(SystemExit) as cm:. This line can be used to determine when the code exits when an exception is raised or if it exits with a code. In this case, I wanted to make sure that the function exits with a code of 0. So after the function runs, I put this line self.assertEqual(cm.exception.code, 0) right after the function to make sure it worked properly before comparing the return value with theexpected_html_content` variable.

What did I learn From Testing and What do I Think of it?

Overall, since I have had no real testing experience, other than looking at testing code my professors would write for my class. I feel that I learned quite a bit from the testers I wrote. I learned how I could make temporary files and folders to work with the function I made. Which I could then use on any functions that handle file or folder input in any future Python applications I make. Additionally, I know how to test the return value of other functions that I make, whether they return a value or a bool. Based on this, I think that I would create testers for any projects I would make in the future, as while it was somewhat time consuming, I still enjoyed it as to me, it added another layer of confidence that the code was working.

Well, that concludes today's post. Thank you all for reading and continuing to follow my journey through programming. I'll catch you in the next post!

Picking out a Formatter and Linter for my Open Source Project

Marco Pasqua — Fri, 03 Nov 2023 01:13:37 +0000

Hey everyone, I recently had the chance to install a linter and formatter for my TXT to HTML Converter program. For formatting I went with Black and for linting, I chose Ruff. I'll talk about why I chose them, how they work, and what changes they made to my code below.

What is Black?

Black is a Python code formatter that will format your code on the fly to match the code style set by the developers. For example, if a line of code is too long, Black will split it up into 2 or more lines for readability. If there are several arguments in a function, Black will also split that up into 2 or more lines. I chose Black, as I liked its code style and the way I can configure it. It was also a project I stumbled across during Hacktoberfest, but since I never used the formatter before I didn't really know how it works so I wouldn't be able to contribute to issues as easily. So I figured I should learn it now, and maybe contribute to it in the future.

What is Ruff?

Ruff is both a formatter and linter written in Rust that promises to be faster than alternative Python linters out there. Now, you may be thinking to yourself, why not chose Ruff for both linting and formatting? It would make things much easier. Well, I mainly chose for Ruff to be just a linter, as like I said above, I wanted to learn how Black works and try to contribute to it in the future. I can also do the same with Ruff, if I learn how their linter works, I can technically learn how two open source projects work and try to contribute to them both. Additionally, Ruff provides the same method for configuration as Black, which is another benefit I'll talk about later.

How was Black and Ruff set up?

Both Black and Ruff had very simple installation processes. I'll talk about how I set them up for Windows running PyCharm as my IDE.

Black:

To install Black, all I had to was type pip install black into my terminal. Black is designed to run on Python 3.8 or newer, and since I'm running my project with Python 3.11.4, it had no problem installing. What was nice about Black is that it worked straight after downloading, there was no setup involved. I could type black . into my terminal and have it format all of my Python files immediately. However, there were some files I did not want it to format, specifically a Python file I'm using for reading a Dictionary from for a sidebar feature I'm developing. So while I could run black file1.py file2.py file3.py. I would rather configure it to ignore one file and format the rest with black . instead. Here's how I did it. To configure Black you have to create a pyproject.toml file. From there you have to specify the tool that reads configuration, and then tell the tool what to exclude by using regex. Like the example I made below

[tool.black]

extend-exclude = '^/sidebar.py'

Since I was using PyCharm as my IDE, Black added itself as a tool without me having to do anything. This gave me the option to configure my IDE to use Black when I save the file or reformat it, which I took advantage of. Since it saves me time from typing it into my terminal. To change the settings for Black on PyCharm, I had to go to Preferences or Settings -> Tools -> Black. That's pretty much it for the set up process, it was quick and easy and Ruff was about the same.

Ruff:

Setting up Ruff was roughly the same as Black. I had to paste this line of code pip install ruff into PowerShell. Then once it installed I could use it without having to configure anything, which is something I appreciated. Before I got to using it, I had to configure it. Just like Black, Ruff also uses a pyproject.toml file for configuration. So I was able to use the same configuration file for Black with Ruff. All I had to do was specify that Ruff will be reading the information after a certain line. With the configuration I was able to tell Ruff what kind of code style it should look for, what warnings it should ignore and what to exclude from linting. You can see the configuration I used for Ruff below, which I was able to put right under the configuration for Black.

[tool.ruff.lint]
select = [
  # pycodestyle
  "E",
  # Pyflakes
  "F",
  # pyupgrade
  "UP",
  # flake8-bugbear
  "B",
  # flake8-simplify
  "SIM",
  # isort
  "I",
]
# Asking ruff to ignore the number of characters per line. PyCharm IDE already takes care of it.
ignore = ["E501"]
#Exclude certain files and folders from linting
exclude = [
    ".git",
    ".examples",
    ".app",
    "sidebar.py",
    "til",
    ".ruff_cache",
]

Originally, I did not have the ignore there, but I'll talk about why I used it later. Unlike Black, Ruff was not already added as a tool to PyCharm. There is a way to add it as an external tool, but it didn't work for me. Thankfully, there on Ruff's website they mentioned a member in the community who created a PyCharm plugin for Ruff and according to reviews they commonly updates it. So it was something I could rely on. Downloading the plugin was really simple, I just had to go to Preferences or Settings -> Plugins and search for Ruff on PyCharm. I found it and download it to my IDE. Then to configure it I had to go to Preferences or Settings -> Tools -> Ruff. Doing this greeted me to very similar option that Black had, I could run Ruff when I saved the file or reformatted it. Since I'm using Black for formatting, I made sure to configure the Ruff plugin to not be used when reformatting. If you did want to run Ruff on the terminal you could just type ruff check . to lint all the files in the current directory. If Ruff finds any issues, you could have it attempt to fix them by using ruff check . --fix. Ruff also has some other linting options you can use to help out. That was pretty much it.

What did Black and Ruff Find and Change in my Code and How Did I Use Them?

Black:
When I used Black, I first tried it out from by using this line of code black . on PowerShell, after I configured it to ignored one of my files. Black found out that a lot of my lines were too long for the Python standard. This is something that I kind of knew, since PyCharm makes highlights this issue for me. I mainly do on all my programming on a monitor that is connected to my laptop. So I tend to write longer lines of code. However, if I drag the IDE window to my laptop's display, it can be harder to read some of the lines of code. So, Black fixed that for me. I also noticed that with some lines where I do string concatenation Black split up each part of the string on separate lines. I didn't mind it, as it felt like my code looked a little neater and easier to read. The easy to read part is something I strive for with my code, so I was thankful for it. When I integrated Black into my IDE with the steps I mentioned above, I also tested it make sure it was working by handing it an unformatted line of code, which it fixed.

Ruff:
Just like Black, I used Ruff on PowerShell first with the command ruff check . to lint my files, I of course did this after I configured Ruff. Ruff seemed to think that some of line of code and comments were still to long, which was something that PyCharm was also suggesting to me. Before I tried fixing it myself I did try to use ruff check . --fix, and it was able to fix a handful of the 20+ problems it found. It was helpful, but I had to go fix some by hand, and thankfully my IDE provided me suggestions on how to change my lines of code, which I let it do for me. However, a lot of the lines seemed both fine to me and my IDE, which was when I configured Ruff to ignore = ["E501"] (it's a rule that states how many characters long my lines should be). PyCharm already seems to handle part of this for me, and if I did want to check with Ruff I can always uncomment the line. One other issue, Ruff picked up was that I was importing everything (*) from my helper.py file into my file_processors.py file. I didn't really see an issue with this until I realized I had a function from helpers.py that was not used in the file_processors.py, that function being the one that handles sidebar creation. Realizing that I did not need to import a function that would not be used in file_processors.py I changed up my import for the helper.py file to import only the functions I need, which I then formatted with Black. I also tried out the Ruff extension on my code and it worked just fine.

What did I learn?

Other than the fact that I got to learn how to use a very helpful formatter and linter, I also got to learn a little more about the proper way to style my code in Python since I feel like my code is now a look more easier to read and digest. Which should make future revisions easier not just for me, but anyone else modifying my code.

That concludes this post. Thank you all for reading, and I hope you found my little setup tutorial helpful! Catch you in the next post!

Summary of Hacktoberfest

Marco Pasqua — Tue, 31 Oct 2023 19:09:16 +0000

Hi everyone, seeing as how today is the last day of Hacktoberfest I figured it would be appropriate to make a recap of my Hacktoberfest experience.

What Did I do During Hacktoberfest and How did I progress?

During Hacktoberfest, I made four PRs to other repos. You can learn about them in the blog posts below, but I'll also summarize some of them.

Before I started making my contributions, I had a hard time finding a repo to contribute to as I was coming across a lot of big repos that made me nervous to work on. I knew that I had to start off small and work my way up to make myself more comfortable. I first started off by updating the documentation on a repo to have a table of contents, which is my first post. The next contributions I made were enhancements to repos I found. These enhancements ranges from adding in new calculators to a project, as seen in my second and fourth blog post. To updating the logos used for X (formerly Twitter) that were used in the repo I selected for my third blog post.

What did I learn?

I learned a few things about Docker, which I had to use in my third contribution. I also learned that people in the open source community can be really friendly when assigning an issue to you and will offer to help you where they can. Since in my third issue, I struggled with getting the logo to display in its respective colour for dark and light mode. The repo owner gave me some advice, but I decided to try something that I found online which managed to work for me and the owner. Going forward I know that I don't have to be so shy when it comes to working on other repos and solving their issues, since the owners are also in it to make sure that their project can be the best it can be.

That concludes this blog post, once again thank you for reading this post and following my journey through Hacktoberfest. It means a lot and I'll catch you all in the next post.

Adding a Table of Contents Feature to my Project

Marco Pasqua — Mon, 30 Oct 2023 20:15:40 +0000

Hi everyone, as mentioned in my last blog post. I mentioned that I wanted to add in a sidebar feature to my txt to html convertor project. Well, I did just that, the new feature is up and running in my program, and while it is still more in its prototype phase. It's still working. However, instead of a sidebar it's a table of contents, for now.

What is the Sidebar Feature?

The sidebar feature in my program works very similarly to the same feature offered by Docusaurus. However, instead of generating a sidebar it just makes table of contents, as mentioned above. This works in my program, by reading the contents of a dictionary stored in a file called sidebar.py that exists within the root of the txt to html convertor's folder. The dictionary looks like this:

table_of_contents = [
    {'label' : 'TIL How to Get Command Line Arguments in Python', 'url' : 'TIL How to Get Command Line Arguments in Python.html'},
    {'label' : 'TIL rmtree and os Library', 'url' : 'TIL rmtree and os Library.html'}
]

It works by taking in the URL or path of a file and writing that path to an HTML <a> tag while also giving it a label based on the user's choice. In this case, I chose to name it after the files I wanted to include in the table of contents. This feature basically aims to save the user some time from creating a table of contents, as for example if they wanted to process a folder made up of txt or md files, they can not only process them but also link them all together with the use of the sidebar feature.

How did I Make it?

To implement this feature, I first added in a new optional argument to be entered from the command line. This argument being --sidebar and -sb. When invoked, the user provides the path of their sidebar.py file (which is something that I don't want them to do. I just want them to be able to use the optional argument without having to provide the file path. So I would need to fix this in a future commit). After they provide the file, the program begins creation of the HTML file. But before that, it starts by processing the content from the dictionary in the sidebar.py file into a table of contents to be used in the body of the HTML file. I tested this out and found it was working, but noticed a issue existing in my code that I have found before. When processing a Markdown file with the bold (**) syntax, the code was supposed to convert the text in the syntax to the <strong> HTML tag. However, this wasn't working anymore. So I left a comment for myself and created a new issue identifying which branches and issues to look at when I decide to tackle the bug.

How did Docusaurus Inspire my Feature?

When using Docusaurus, I liked the sidebar feature. As mentioned above, this feature is meant to be a little bit of the time saver for the user when generating a website with several pages. That's exactly how I saw this feature in Docusaurus, so that's the feature I wanted to implement in my project.

Comparison with Docusaurus' Sidebar and txt to HTML Convertor Sidebar

There are some similarities and differences between my implementation of the sidebar and Docusaurus' version. Similarly with both implementations, they read a dictionary from a sidebar file and get the information from the dictionary by importing it to a function that handles the generation of the sidebar. They both rely on keys from the dictionary when creating certain parts of sidebar. The differences are, that at the moment my sidebar implementation only makes a table of contents, and I don't need a config file that requires the path of the sidebar file in order to generate it.

Next Steps for the Feature

As you might be able to tell, my next big step for the feature is to make an actual sidebar. I think I might be able to just use some CSS to get this done, but I may have to look into it more as web development is not my strong suit, so I could be underestimating this. If you're good with web development and might have an idea of how I can implement this idea, feel free to leave a comment on the issue I made for it. There is one other thing I want to figure out. I mentioned earlier that when using the sidebar argument I don't want the code to require a file path input from the user. Since right now I have the code hardcoded to read the dictionary from the sidebar file, and I think that it's fine to read it like that. I might just leave this problem on the backburner for now as I just see the problem as more of a minor inconvenience to the user. So my main next step to tackle to creating an actual sidebar.

That about sums up my feature and what I plan to do improve it in the future. As always, thank you for reading and I'll catch you in the next post.

Learning About Docusaurus

Marco Pasqua — Mon, 30 Oct 2023 15:47:06 +0000

Hi everyone, today I'm going to be talking about Docusaurus. Docusaurus is an open source project backed by Meta, which allows developers to build a documentation website, portfolio or blog website entirely from Markdown and/or React JS. It can be really handy for those who aren't fans of web development (like me), or those who just want to push out a quick and simple website. There are several other features that it provides, but I'll be talking about one of those features that I would like to implement in my txt to html convertor project and how I tried to examine the code implementation of the feature on Docusaurus.

What's the Feature I want to Implement?

Docusaurus has the ability to generate a sidebar for your site, which can act like a table of contents to help the user navigate through the pages of your site. To create a sidebar with Docusaurus you must make sidebars.js file in the root of your website folder. In the sidebars.js file, you must make a dictionary that links to the pages of your website. Docusaurus makes one by default, however you can also make your own or remove it if you'd like. To make you own, you can do something like this;

const sidebars = {
  tutorialSidebar: [
    'intro',
    {
      type: 'category',
      label: 'Getting Started',
      items: ['tutorial-basics/create-a-document', 'tutorial-basics/create-a-blog-post'],
    },
    'hello',
    'tutorial-basics/create-a-page'
  ],
};

Words in the dictionary like intro and hello link to Markdown files in the root of the docs folder. Doing something like 'tutorial-basics/create-a-page' also links a file that is in the docs directory, but gets the file from the tutorial-basics directory that is within the docs directory. You can also make a nested part of the side bar with the

{
      type: 'category',
      label: 'Getting Started',
      items: ['tutorial-basics/create-a-document', 'tutorial-basics/create-a-blog-post'],
    },

part. You can assign a label like "Getting Started" and then inside of the label, you can have several different links to other pages within the items tag. I also forgot to mention, that in the markdown files, you can assign a position of the file to the sidebar. For example, in my intro.md file I could do something like this

---
sidebar_position: 1
---

to say that I want this file to appear first in the sidebar. If I wanted to change the position, I can give it a value of 2 or more.

Strategies used to Find the Official Implementation

With that out of the way, we can get to the strategies I used to try to find the official implementation of the feature. I did a couple of ideas on how the developers could have made it, based on the sidebars.js file that needs to be created. But they were more of vague ideas and I needed a better idea of what was done. I used a few strategies, so I'll list them out below.

I first tried using git grep on my repo to try to find any sign of how sidebars are handled within the files of the website. I found out that the sidebar file must be mentioned in the docusaurus.config.js file, this was a good start. Since I then followed the sidebarPath key from the dictionary which brought me to a new file called plugin-content-docs.js. The file contained a lot about side bars, so I search the file for instances of where the word "sidebar" is mentioned and found a function called SidebarItemsGeneratorOption that links to a file called types in a sidebars folder. This was a good I was able to find what might be the folder containing most of the sidebar logic. I followed the path to the folder that Visual Studio provided. I ended up finding a file called generator.ts which included a generateSidebar function. Reading through the file was a little confusing for me (since JavaScript isn't my strong suit), but from my understanding the way the sidebar is generated is split into 4 steps based on comments provided by the developers;

Step 1: The code extracts docs in the autogenerated directory.
Step 2: The code then turns the extracted files into a tree structure.
Step 3: The code then recursively transforms the tree to sidebar items, which is where the generateSidebar function comes in. It looks like the function handles the naming of the items in the sidebar, the creation of the category and assigning a position and id.
Step 4: The code finally recursively sorts through the categories/docs and removed the position attribute from the final output, as it is only used for the sorting. It then returns the generated and sorted sidebar to be displayed.

I also tried to use GitHub's code search feature, but perhaps I was using it incorrectly, as searching for the feature implementation only brought me to other people's websites on my first search. I did one more search, which was this time formatted to look specifically at repos owned by Meta that include the works "Docusaurus" and "sidebars" which brought me to the code I found with git grep in my first step. So I basically found the same thing.
I finally used ChatGPT to try to help me. I already had the idea that everything relevant to the sidebar was being handled in the sidebar folder, so I can always look there for help. But I did kind of want a simplified idea and I could also use it in case I needed an explanation of the code written by the developers. The simplified idea was more of just making a basic table of contents, since that's basically what the sidebar is, I could maybe make the actually sidebar with some CSS. It helped me refine the idea of making an optional argument for a table of contents (sidebar) that takes in an additional python file that includes a dictionary keys and values that link to other pages in the website.

Based off of the 3 methods that I used to help me understand the way sidebars are handled. Using git grep probably helped me the most, as I was able to find out how the feature is implemented. It also helped a little with figuring out how to make proper comments. Most of the variables and functions names are somewhat self explanatory, but the comments left within the files mainly provide a walk through of everything that was done, while also explaining what values certain variables contain. I already do the latter, but not the former when I make comments. I find that I make too many comments some times, as I find myself occasionally making comments on most variables names. However, making comments in a walkthrough type of way can be very helpful to me and the person reading my code. ChatGPT also helped me, as I used it to help simplify some of the ideas I had in my head for the implementation. Although, I can also use it for explaining the dev's code, which may prove useful in the future when I work on the feature.

That's it for now. Thank you all for reading! I'm going to get to work and see if I can make a prototype for a table of contents to be generated in my project.