Add install, test instructions

[Adrijaned]

@Jajasek There are no instructions on how to install or test this.

First step for fixing this might well be generating a requirements.txt file for this module, so at least the dependencies can be installed.
Then, providing instructions on how to set up the structure of this project would be nice, preferably through the means of full walkthrough up until the point of running your included example.

I've already tried setting this up myself, by generating a fresh virtualenv for this module, installing just pygame inside, and straightaway trying to run the example (all from the shell), that however obviously failed straight on trying to import pygae-widgets.

[Jajasek]

Where did you save the library? It should be saved in the folder <your installation of python>/Lib/site-packages/pygame_widgets. There should be also the pygame folder here.

[Adrijaned]

I believe to have created the symlink to this repo's dir in the right dir under venv, as I no longer error on importing; however, the next issue I face is as following:

pygame_widgets on  master [?] via 🐍 v3.7.6(venv) 
❯ python3 examples/bouncing_ball.py 
pygame_widgets init
pygame 1.9.6
Hello from the pygame community. https://www.pygame.org/contribute.html
Traceback (most recent call last):
  File "examples/bouncing_ball.py", line 1, in <module>
    import pygame_widgets
  File "/home/adriFedora/PycharmProjects/pygame_widgets/venv/lib/python3.7/site-packages/pygame_widgets/__init__.py", line 5, in <module>
    from pygame_widgets.widgets.widget import *
  File "/home/adriFedora/PycharmProjects/pygame_widgets/venv/lib/python3.7/site-packages/pygame_widgets/widgets/widget.py", line 6, in <module>
    import pygame_widgets.constants.private as CONST
  File "/home/adriFedora/PycharmProjects/pygame_widgets/venv/lib/python3.7/site-packages/pygame_widgets/constants/private.py", line 5, in <module>
    class DEFAULT:
  File "/home/adriFedora/PycharmProjects/pygame_widgets/venv/lib/python3.7/site-packages/pygame_widgets/constants/private.py", line 26, in DEFAULT
    class LABEL:
  File "/home/adriFedora/PycharmProjects/pygame_widgets/venv/lib/python3.7/site-packages/pygame_widgets/constants/private.py", line 27, in LABEL
    bg = THECOLORS['transparent']
KeyError: 'transparent'

[Jajasek]

Oh no, I have forgotten...
Pygame has module colordict.py, where it defines a dictionary THECOLORS, which contains LOTS of colors... I have edited the file and added the color "transparent" = (0, 255, 0, 0) and I use it internally in my library. I hope, that forcing all users of pygame_widgets to do the same isn't illegal...

[Jajasek]

But I am happy you managed to run it and I hope it is the only little issue. What is your operating system?

[Adrijaned]

Forcing your users to edit an external library locally is quite a big no-no. You could either try to get your edit merged upstream, or, just use some sort of hack to get around it locally.

[Adrijaned]

And as for the OS... my username as seen from the log should be big enough hint.

[Adrijaned]

Like, couldn't you just edit https://github.com/Jajasek/pygame_widgets/blob/master/constants/private.py#L27 to whatever constant you need?

[Adrijaned]

Wait, that's too simple solution, and also it just moves the error to the other places where the constant is used. Throw THE_COLORS['transparent'] = (0,255,0,0) near the top of pygame_widgets/constants/public.py instead.

[Adrijaned]

Also Tests/test_button_entry.py fails with

  File "Tests/test_button_entry.py", line 29, in <module>
    Textove_pole = pygame_widgets.Entry(Okno, (100, 100), (200, 20))  # FIXME: entry initialization fails
  File "/home/adriFedora/PycharmProjects/pygame_widgets/venv/lib/python3.7/site-packages/pygame_widgets/widgets/entry.py", line 47, in __init__
    self._safe_init(**kwargs)
  File "/home/adriFedora/PycharmProjects/pygame_widgets/venv/lib/python3.7/site-packages/pygame_widgets/widgets/widget.py", line 665, in _safe_init
    self._generate_surf()
  File "/home/adriFedora/PycharmProjects/pygame_widgets/venv/lib/python3.7/site-packages/pygame_widgets/widgets/entry.py", line 75, in _generate_surf
    I.Image._generate_surf(self)
  File "/home/adriFedora/PycharmProjects/pygame_widgets/venv/lib/python3.7/site-packages/pygame_widgets/widgets/image.py", line 49, in _generate_surf
    self.my_surf = self.image(self)
  File "/home/adriFedora/PycharmProjects/pygame_widgets/venv/lib/python3.7/site-packages/pygame_widgets/constants/public.py", line 270, in func
    surf = Surface(size, SRCALPHA)
ValueError: size needs to be (int width, int height)

[Adrijaned]

oh, and could you please put if __name__ == "__main__": guard in all of your python files which might attempt to execute something?

[Jajasek]

Why exactly? And which modules do you mean? I don't think I need to distinguish running as main from importing in any of my modules.

[Adrijaned]

Modules Tests and examples, I'm trying to sorta hook-up some docs-generators, and they usually rely on recursively importing everything and reading docstrings on that.

[Jajasek]

OK, that's good reason.

Wait, that's too simple solution, and also it just moves the error to the other places where the constant is used. Throw THE_COLORS['transparent'] = (0,255,0,0) near the top of pygame_widgets/constants/public.py instead.

Done. You maybe wondered, why I haven't done this before. I have tried this, but PyCharm didn't auto-complete the key while the others did. So I updated the definition only because of my comfort. And then I forgot it. So now I have added it to public.py and updated the instalation steps.

As for the failure of Tests/test_button_entry.py, I know about it. The Entry widget is in development and has a lot of errors... But it should have failed with NotImplementedError, not ValueError, so I "fixed" it.

[Jajasek]

oh, and could you please put if __name__ == "__main__": guard in all of your python files which might attempt to execute something?

I think it should now be all done.

[Adrijaned]

Alright. I'm off the PC now already, but will make sure to check it out for good tomorrow.

…

On Tue, Apr 21, 2020, 10:55 PM Jajasek ***@***.***> wrote: oh, and could you please put if __name__ == "__main__": guard in all of your python files which might attempt to execute something? I think it should now be all done. — You are receiving this because you authored the thread. Reply to this email directly, view it on GitHub <#2 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AFJM3HLA7IDQSTC44AJOVH3RNYB4VANCNFSM4MNI6U6A> .

[Adrijaned]

I've finally gotten the documentation to build using pdoc3 and netlify from my fork of this repository, you can see the documentation live on https://amazing-curran-ee8b74.netlify.app/ . I deleted all files from /Tests/ as they were generally not running and causing various other problems. Also, don't ever use the if __name__ == "__main__": guard in the form you did in the commit f5feb27 - documentation generators or even some linters and other stuff rely on importing all the files in workspace, and what you did basically terminates the whole process, causing weird errors in result (imagine you accidentally imported one of the files, and suddenly your program was crashing on launch without any error messages and with clean status code). I fixed the import guard in the example, as it was quite easy, and I also added some nonsensical documentation to the packages themselves just so that it can be viewed on the website. The pdoc3 added to requirements is the actual tool used for building the documentation, and file runtime.txt is used to select python version on netlify then.

[Jajasek]

Also, don't ever use the if __name__ == "__main__": guard in the form you did in the commit f5feb27 - documentation generators or even some linters and other stuff rely on importing all the files in workspace, and what you did basically terminates the whole process, causing weird errors in result (imagine you accidentally imported one of the files, and suddenly your program was crashing on launch without any error messages and with clean status code).

Oh, sorry, I didn't realize that. It is fixed now.
I have also added README and LICENCE to my game Pampuch, that uses pygame_widgets. Would you be able and willing to download and test it?

[Adrijaned]

Could you just quickly throw together a setup.py for this repository so that it can be installed in a sane way? https://docs.python.org/3/distutils/setupscript.html

[Jajasek]

Do you mean Pampuch or pygame_widgets?

I'm not sure, if I understand it right; where should I put the setup.py, say, if I would want to distribute pygame_widgets? In the root folder of pygame_widgets?

[Jajasek]

Also, what about the dependencies? Can I specify extarnal libraries, that will be automatically downloaded and installed? If not, what is the point of setup.py in my case?

[Adrijaned]

setup.py for pygame_widgets.

Using setup.py allows for instalation of module using pip install, instead of having to manually copy/link files over to system directories. https://stackoverflow.com/a/1472014/6546996

You want the setup.py file be in the same directory as the root folder of your package - in this case, due to how this repository is laid out, in a directory parent to this repository. Ideally, you should move the whole python project one directory down, that way you also wouldn't have to embed completely unrelated files in your python package (PDF is something that really should not be in a python package) (i.e. create a new directory pygame_widgets in the root of this repo, move all the subpackages and __init__.py inside that directory, leave everything else where it is)

As far as dependencies go, that's what requirements.txt is for, and they should be transcluded into setup.py as per https://stackoverflow.com/a/53069528/6546996