Updating documentation, exposing methods for package

.gitignore

@@ -127,3 +127,5 @@ dmypy.json
 
 # Pyre type checker
 .pyre/
+
+.DS_Store

README.md

@@ -1,2 +1,97 @@
 # gaurabda-calendar
 Python library for calculating panchanga calendar with vaisnava events.
+
+## Installation
+
+```
+pip install gaurabda
+```
+
+## Using
+
+Here are a few examples of code that you can try quickly. Examples are related
+to calculation of calendar. Before calendar calculation we need to specify
+location and start date.
+
+We can obtain location object basically in two ways:
+
+* create new location
+
+```
+# create new location
+
+loc = gcal.GCLocation(data = {
+ 'latitude': 27.583,
+ 'longitude': 77.73,
+ 'tzname': '+5:30 Asia/Calcutta',
+ 'name': 'Vrindavan, India'
+})
+```
+
+List of all timezones can be obtained by calling `gcal.GetTimeZones()`.
+
+* find location in existing list
+
+```
+# find existing location
+
+loc = gcal.FindLocation(city='Vrindavan')
+```
+
+List of all countries `gcal.GetCountries()` and list of cities for given country: `gcal.GetLocationsForCountry('India')`. Function GetLocationsForCountry has optional parameter limit, that takes whole number limiting number of locations returned by this method. Default value is -1, that means there is no limit.
+
+
+Then we need create date object.
+
+```
+today = gcal.Today()
+print(repr(today))
+
+date1 = gcal.GCGregorianDate(text='24 apr 2017')
+print(repr(date1))
+```
+
+Constructor for GCGregorianDate contains more optional parameters:
+
+* **year**, **month**, **day** that are whole natural numbers, year between 1500 - 2500, month 1-12, day according given month
+* **shour** is from interval 0.0 up to 1.0 where 0.0 is mignight, 0.5 is noon (12:00 PM) and 1.0 is next midnight.
+* **tzone** is offset from UTC 0:00 in hours, so value +5.5 means offset 5:30, which is actual for India
+* **date** is existing GCGregorianDate object
+* **text** can be text form of date (e.g. '24 Apr 2017')
+
+Parameters can be combined with certain succession of evaluation. Parameters are evaluated in this order, where later parameter overrides previous values.
+
+* text
+* date
+* year
+* month
+* day
+* shour
+
+So for example, to get first day of current month, we may use:
+
+```
+d = gcal.GCGregorianDate(date=gcal.Today(), day=1)
+```
+
+Next step is to create calculation engine for calendar, execute calculation and write results to file:
+
+```
+# create calculation engine and calculate
+tc = gcal.TCalendar()
+tc.CalculateCalendar(loc,today,365)
+
+# save results in various formats
+with open('calendar.txt','wt') as wf:
+ tc.formatPlainText(wf)
+with open('test/calendar.rtf','wt') as wf:
+ tc.formatRtf(wf)
+with open('test/calendar.html','wt') as wf:
+ tc.writeHtml(wf)
+with open('test/calendar2.html','wt') as wf:
+ tc.writeTableHtml(wf)
+with open('test/calendar.xml','wt') as wf:
+ tc.writeXml(wf)
+```
+
+Argument for formatPlainText/formatRtf/etc. is writer, so it can be any text stream from `io` module.

gaurabda/GCCountry.py

@@ -39,6 +39,9 @@ def FindCountry(name=None,abbr=None):
  return a
  return None
 
+def GetCountries():
+ return [a['name'] for a in gcountries]
+
 def GetCountryName(w):
  bytes = int(w).to_bytes(2,byteorder='little',signed=False)
  abbr = chr(bytes[0]) + chr(bytes[1])

gaurabda/GCGregorianDate.py

@@ -1,5 +1,6 @@
 import math
 import datetime
+import re
 
 import gaurabda.GCMath as GCMath
 import gaurabda.GCUT as GCUT
@@ -62,16 +63,20 @@ def CalculateJulianDay(year, month, day):
 
 
 class GCGregorianDate:
- def __init__(self,year=2000,month=1,day=1,shour=0.5,tzone=0.0,date=None,addDays=0):
- if date!=None:
- self.Set(date)
- else:
- self.year = year
- self.month = month
- self.day = day
- self.shour = shour
- self.tzone = tzone
- self.InitWeekDay()
+ def __init__(self,year=None,month=None,day=None,shour=None,tzone=None,date=None,text=None,addDays=0):
+ self.year = 2000
+ self.month = 1
+ self.day = 1
+ self.shour = 0.5
+ self.tzone = 0.0
+ if text != None: self.SetText(text)
+ if date!=None: self.Set(date)
+ if year != None: self.year = year
+ if month != None: self.month = month
+ if day != None: self.day = day
+ if shour != None: self.shour = shour
+ if tzone != None: self.tzone = tzone
+ self.InitWeekDay()
  if addDays!=0:
  self.AddDays(addDays)
 
@@ -87,6 +92,34 @@ def __repr__(self):
  def time_str(self):
  return "{:02d}:{:02d}:{:02d}".format(self.GetHour(), self.GetMinute(), self.GetSecond())
 
+ def MonthAbrToInt(self,text):
+ if len(text)>3: text=text[:3]
+ for i in range(65,78):
+ if GCStrings.getString(i).lower()==text.lower():
+ return i-64
+ raise
+
+ def SetText(self,text):
+ y = 2000
+ m = 1
+ d = 1
+ sh = 0.5
+ tz = 0.0
+ mr = re.match( r'([0-9]+) ([A-Za-z]+) ([0-9]+)', text )
+ if mr:
+ try:
+ d = int(mr.group(1))
+ m = self.MonthAbrToInt(mr.group(2))
+ y = int(mr.group(3))
+ self.year = y
+ self.month = m
+ self.day = d
+ self.NormalizeValues()
+ except:
+ return
+ return
+
+
  def IsLessThan(self,date):
  y1,m1,d1,h1 = NormalizedValues(self,tzone=True)
  y2,m2,d2,h2 = NormalizedValues(date,tzone=True)

gaurabda/GCLocation.py

@@ -44,11 +44,13 @@ def __init__(self,data=None):
  self.m_nTimezoneId = data['tzid']
  self.m_strTimeZone = GCTimeZone.GetTimeZoneName(id=self.m_nTimezoneId)
  self.m_fTimezone = GCTimeZone.GetTimeZoneOffset(id=self.m_nTimezoneId)
- else:
- if 'tzname' in data:
- self.m_strTimeZone = data['tzname']
- if 'offset' in data:
- self.m_fTimezone = data['tzoffset']
+ elif 'tzname' in data:
+ tzone = GCTimeZone.GetTimeZone(name=data['tzname'])
+ self.m_nTimezoneId = tzone['id']
+ self.m_strTimeZone = data['tzname']
+ self.m_fTimezone = tzone['offset']/60.0
+ elif 'offset' in data:
+ self.m_fTimezone = data['offset']
 
  @property
  def m_strLongitude(self):

gaurabda/GCLocationList.py

@@ -40,6 +40,22 @@ def Add(loc):
  locationList.append(loc)
  m_bModified = True
 
+def FindLocation(city=None,country=None):
+ for L in locationList:
+ if city==None or city==L.m_strCity:
+ if country==None or country==L.m_strCountry:
+ return L
+ return None
+
+def GetLocationsForCountry(country=None,limit=-1):
+ rv = []
+ for L in locationList:
+ if country==None or country==L.m_strCountry:
+ if len(rv)<limit or limit<0:
+ rv.append(L)
+ return rv
+
+
 def RemoveAt(index):
  del locationList[index]
  m_bModified = True

gaurabda/GCTimeZone.py

@@ -21,13 +21,20 @@ def ID2INDEX(_id):
  return i
  return None
 
-def GetTimeZone(id=None,index=None):
+def GetTimeZone(id=None,index=None,name=None):
+ if name!=None:
+ for tidx,t in enumerate(gzone):
+ if t['name']==name:
+ index = tidx
  if id!=None:
  index=ID2INDEX(id)
  if index==None:
  raise
  return gzone[index]
 
+def GetTimeZones():
+ return [g['name'] for g in gzone]
+
 def GetTimeZoneName(id=None,index=None):
  if id!=None:
  index=ID2INDEX(id)

gaurabda/__init__.py

@@ -3,5 +3,8 @@
 from .TCoreEvents import TCoreEvents
 from .TMasaList import TMasaList
 from .TToday import TToday
-from .GCGregorianDate import GCGregorianDate
+from .GCGregorianDate import GCGregorianDate,Today
 from .GCLocation import GCLocation
+from .GCLocationList import FindLocation,GetLocationsForCountry
+from .GCCountry import GetCountries
+from .GCTimeZone import GetTimeZones

setup.py

@@ -1,16 +1,19 @@
 from distutils.core import setup
+
+curr_ver = '0.7.4'
+
 setup(
  name = 'gaurabda', # How you named your package folder (MyLib)
  packages = ['gaurabda', 'gaurabda.GCEnums'], # Chose the same as "name"
  include_package_data = True,
  package_data = {'gaurabda': ['res/*.*']},
- version = '0.7.3', # Start with a small number and increase it with every change you make
+ version = curr_ver, # Start with a small number and increase it with every change you make
  license='MIT', # Chose a license from here: https://help.github.com/articles/licensing-a-repository
  description = 'Calculation of Gaurabda calendar (Gaudiya Vaishnava calendar)', # Give a short description about your library
  author = 'Gopal', # Type in your name
  author_email = '[email protected]', # Type in your E-Mail
  url = 'https://github.com/gopa810/gaurabda', # Provide either the link to your github or to your website
- download_url = 'https://github.com/gopa810/gaurabda-calendar/archive/0.7.3.tar.gz', # I explain this later on
+ download_url = 'https://github.com/gopa810/gaurabda-calendar/archive/' + curr_ver + '.tar.gz', # I explain this later on
  keywords = ['gaurabda', 'vaisnava', 'vaishnava', 'ISKCON', 'GCAL'], # Keywords that define your package best
  install_requires=[ # I get to this in a second
  ],