Howdy! Another New Face Here.

Joshua on 2013/03/28 17:09
— edited on 2013/03/28 17:11

Hi, I'm Joshua and I'm looking forward to participating in the upcoming PyWeek! I'm a software engineer by profession and a game maker by obsession.

I need a bit of clarification. I'm planning on using a library I've been working on for quite some time, and it's lived on GitHub for four years now. Does the one month requirement start now(as of this post), or from when I first committed on GitHub?

Toast Python Module

Thanks in advance!

(log in to comment)

Comments

richard on 2013/03/29 00:52:

The one month requirement just means that the library has to have been published and documented over a month from the start of the challenge. Sadly it looks like Toast doesn't meet the documentation criteria (which exists to ensure other challenge entrants would have a reasonable chance of learning to use the library before the challenge).

Joshua on 2013/03/29 04:08:

I have a directory showing example usage of all the classes within my library. But if you are looking for proper documentation, I don't have it.

I guess I'm out then. Shame...

dmreichard on 2013/04/01 04:35:

I believe the rules need further clarification. There are many words open to interpretation in the way they are currently defined. For example:

"If you do have a library you must release it within a reasonable amount of time (at least 1 month) before the challenge starts so that others may have reasonable opportunity of using the library"

No mention of needing documentation here.

"You are allowed to use existing libraries that have been available for at least one month before the challenge (and are well documented)."

Perhaps this should have, "As clarification to aspect number 2" before the rest of the sentence.

"A great resource is the pygame.org cookbook. It is perfectly acceptable to cut-n-paste code from the cookbook, as that code is released and should be considered equivalent to a library."

Which also has absolutely horrible documentation on many of the recipes.

I absolutely agree with the idea that libraries and/or frameworks should be released within a 30 day time frame. Additionally I believe that if we are enforcing a library which has been released for 4 years prior to a competition may not be used by anyone due to poor documentation or lack thereof is hypocritical if recipes from the pygame.org website are allowed. I feel that Joshua's library should either be allowed, or the rules page need updated.

Sorry to be "that guy," but double-standards are not okay in my book.

richard on 2013/04/01 08:24:

The rule exists to prevent someone writing a considerable amount of code before the challenge and having an unfair advantage because no-one else could reasonably use the same code.

Additionally, I have never heard of the Toast package. And I've been around Python gaming for some time, actively poking around new things when I find them. It has not, as far as I can tell, been "released" in any meaningful manner.

You're comparing a package with dozens of modules to snippets in the pygame cookbook. I hardly think the comparison is fair.

richard on 2013/04/01 08:32:

I'll also note that the rules (made up solely by me) are intentionally fuzzy in places, and certainly parts of them have been bent in the past, but on the goal of trying to provide a level playing field for everyone to participate I'm pretty dedicated.

dmreichard on 2013/04/01 15:43:

I'm most certainly in favor of a level playing field, and I don't necessarily disagree with the rule that a library needs proper documentation. Thank you for the follow up Richard.

Joshua:
Toast looks like the kind of framework I began working on several months ago using pygame as a back-end, only more mature and feature rich. Obviously it won't be valid for the competition coming up now, but is there any chance you will be working on documentation so that it would be valid for upcoming competitions?

Also as a side note/suggestion, I implemented a fixed delta time step without using the pygame clock() and instead used platform independent high resolution timers and it worked very well. Just something you might be interested in.

Joshua on 2013/04/03 18:07:

I'm concerned that the fact PyWeek is a competition ultimately hurts the event. The more rules and restrictions you impose, the more exclusive you make it. Rather than focusing on winners, losers, and cheaters, I'd love it if it focused on creativity, community, and the promotion of the language we adore.

richard
I've been around the Python gaming scene, about seven years now. Toast started roughly five years ago as a nameless personal library that I've been constantly tweaking and improving. I've never really had a chance/platform to promote it, and I'm trying to put it out there in hopes that someone might find it useful or learn from it. I'm always up for suggestions or help on making it more visible/useful.

dmreichard
Thanks for the kind words. I've been looking into using Sphinx to generate API documentation, and I've had good results so far. In fact, I might end up spending PyWeek getting this in order and publishing a proper API. I'd also like to get a website going, but that might involve renaming the package so I can find a URL that isn't already taken.

Sure, I'm interested! Feel free to hit me up: joshua.skelton@gmail.com

reidrac on 2013/04/03 20:30:

Joshua: I think you can make a game with your library any time you want, it's just that your entry would be disqualified if submitted to the contest.

The "rules" page starts with 4 points:

Must be challenging and fun,
Entries must be developed during the challenge, and must incorporate some theme decided at the start of the challenge,
Will hopefully increase the public body of python game tools, code and expertise,
Will let a lot of people actually finish a game, and
May inspire new projects (with ready made teams!)

IMHO that's the important part, and it says nothing about winning the contest!

Joshua on 2013/04/03 21:08:

reidrac
You make some very good points, you've got me there! I do make games with my library, but the pressure of getting something done and actually released helps.

Actually I'm pretty excited about getting my little library in better shape. I'm planning on refactoring the package structure to something more pythonic, adding documentation, and possibly adding it to pypi. Any guidance would be appreciated.

reidrac on 2013/04/04 07:23:

You can start using GiHub features (see GitHub pages for a nice project website and Sphinx output, and the Wikis for a start with the documentation).

I would recommend you using some sort of release process maintaining a "changelog" and tagging versions in GiHub, so any potential user knows which code can be considered "usable" (sometimes the git repo can be in a unstable point).

After that adding the library to PyPi shouldn't be that difficult :)

richard on 2013/04/04 09:40:

Joshua: I recommend participating in PyWeek using your library and making sure it's clear that's what you're doing. If people wish to disqualify you because if it they can. I don't recall that anyone has ever come close to disqualification before :-)

richard on 2013/04/04 09:41:

Oh, the reason I recommend participating even with the risk of DQ is that it'll give you a chance to focus on a single project for a week and really kick the tyres of your library. And it might help you focus on places that could use documentation :-)

richard on 2013/04/04 09:42:

Woo! Third comment in a row: publish to PyPI with a good (not long, but comprehensive) description so people know what you're releasing. That'll get the word out. A post to reddit /r/Python would also help (though I'd probably do that for you if you released to PyPI :-)

Cosmologicon on 2013/04/04 13:41:

For what it's worth, I haven't looked at your project personally, but I hate when libraries forgo API documentation for examples. The examples are always helpful for the library designer themself, but I need some docs. I would be very unlikely to consider a complex library with no documentation at all "usable".

If the rule actually gets you to write the darn documentation after five years, at the cost of you not using your library for one PyWeek, then I would say that the rule promotes the language far more than it hurts it.

Joshua on 2013/04/04 14:42:

Wow! Thanks for all the help, you folks are great!

richard
Haha. Deal. I'll disclose this upfront, and if I'm DQ'd oh well.

Cosmologicon
I understand your sentiment, and even agree. The thing is, originally I didn't anticipate ever publicly releasing my little library. It was just a collection of things to Get Stuff Done, which as programmers we all have. The examples are mostly there to verify that I don't break anything when I make changes to the underlying objects, but do serve to illustrate example usage.

Cosmologicon on 2013/04/04 15:37:

"The examples are mostly there to verify that I don't break anything" Yeah exactly. It sounds like exactly the kind of private codebase the rule is trying to discourage. FWIW, I think you should spend this week documenting as much as you can, and maybe somebody other than you can actually use it for this time. Better late than never, and all that.

Joshua on 2013/04/04 16:26:

I don't think it is as bad as you think. They are system level and performance tests. Unit testing is great for testing the lower level units, but sometimes it's not enough. For example: when I began to use pygame.Surface.convert(), it was nice to see what expected a per pixel alpha and the impact on overall performance.

Why would you want to discourage someone from participating?

Agreed. I am getting excellent results from Sphinx and am actively trying to get as much documentation as I can. Trying to make this a useful thing outside myself is a major goal.

Question: What is the preferred format of the documentation? Html? Rst?

Thanks again for your input, I do appreciate it.

Cosmologicon on 2013/04/05 01:25:

I don't think it is as bad as you think. They are system level and performance tests.

Yeah.... exactly. I'm saying examples are primarily intended as tests (something you need for development), not as documentation (something you need for distribution). The format is not as important to me, as long as it's there. :)

Why would you want to discourage someone from participating?

Well let's be clear. I don't really care that much one way or the other. Richard has decided that the rule enforcement should be very lax and I accept that. Also, the rule "violation" here is pretty minor: you obviously didn't intentionally hide anything from anyone.

But if someone came in and clearly wanted to violate a major rule (for instance, wanting to submit a game that someone else wrote, or a game they wrote in advance) and they refused to participate without violating this rule, then yeah I would definitely "discourage" them from participating.

Joshua on 2013/04/05 01:56:

Cool. I think I'll go with html, if only for the reason that rst is still pretty new/foreign to me. :)

Understood. Yeah, the rules seem more lax after the discussion here. I can certainly understand in cases of major violation(for the reasons you mentioned) why they wouldn't be appropriate to include in the challenge.

Cosmologicon on 2013/04/05 17:20:

Cool. :) And if it puts your mind at ease, it is virtually impossible for an entry to be officially disqualified. No entry in the history of PyWeek has even come close, no matter how flagrantly they violate the rules. You have to get 50% DQ and I believe the record, which broke like every rule and wasn't even a game, is 7%.

Cosmologicon on 2013/05/05 21:47:

I believe the record, which broke like every rule and wasn't even a game, is 7%.

Aaand... by not including your source code, you've managed to get an 8% disqualification score and break this record. Congratulations. :P

reidrac on 2013/05/06 09:31:

I understand that PyWeek rules are designed so no judge is required and let the organizers (Richard?) to compete, but still doesn't look right that a percentage of DQ is required when there's copyright infringement or the source code is not submitted.

I mean: it is breaking the rules or is not, and asking 50% of the voters to detect that is ineffective and clearly doesn't work (I didn't notice myself that one of the entries was using copyrighted material without license, so I failed to vote DQ :facepalm:).

Anyway, the worst part is that I don't have a windows machine to play Joshua's entry :(

drnlm on 2013/05/06 11:05:

Eyeballing the detailed view, I see 4 DNW comments, and 6 DQ, but the precentages are 28% DNW and 8% DQ, so the DQ percentage calculation looks buggy.

reidrac on 2013/05/06 11:23:

drnlm: I checked the website source code because the rules are not clear enough, I though it was as you said!

The DQ percentage is calculated based on the number of finished entries and not based on the number of votes of that entry. The DNW percentage is calculated based on the number of votes of that entry.

See: https://bitbucket.org/r1chardj0n3s/pyweek/src/6f5093a03ffa/pyweek/challenge/models.py?at=default#cl-429