Instruction:
Write a Python 3 function that can
create uwg objects from input parameters and return the new object.

Response:
def init_input_obj(self):
        """Section 4 - Create uwg objects from input parameters

            self.simTime            # simulation time parameter obj
            self.weather            # weather obj for simulation time period
            self.forcIP             # Forcing obj
            self.forc               # Empty forcing obj
            self.geoParam           # geographic parameters obj
            self.RSM                # Rural site & vertical diffusion model obj
            self.USM                # Urban site & vertical diffusion model obj
            self.UCM                # Urban canopy model obj
            self.UBL                # Urban boundary layer model

            self.road               # urban road element
            self.rural              # rural road element

            self.soilindex1         # soil index for urban rsoad depth
            self.soilindex2         # soil index for rural road depth
            self.Sch                # list of Schedule objects
        """

        climate_file_path = os.path.join(self.epwDir, self.epwFileName)

        self.simTime = SimParam(self.dtSim, self.dtWeather, self.Month,
                                self.Day, self.nDay)  # simulation time parametrs
        # weather file data for simulation time period
        self.weather = Weather(climate_file_path, self.simTime.timeInitial, self.simTime.timeFinal)
        self.forcIP = Forcing(self.weather.staTemp, self.weather)  # initialized Forcing class
        self.forc = Forcing()  # empty forcing class

        # Initialize geographic Param and Urban Boundary Layer Objects
        nightStart = 18.        # arbitrary values for begin/end hour for night setpoint
        nightEnd = 8.
        maxdx = 250.            # max dx (m)

        self.geoParam = Param(self.h_ubl1, self.h_ubl2, self.h_ref, self.h_temp, self.h_wind, self.c_circ,
                              self.maxDay, self.maxNight, self.latTree, self.latGrss, self.albVeg, self.vegStart, self.vegEnd,
                              nightStart, nightEnd, self.windMin, self.WGMAX, self.c_exch, maxdx, self.G, self.CP, self.VK, self.R,
                              self.RV, self.LV, math.pi, self.SIGMA, self.WATERDENS, self.LVTT, self.TT, self.ESTT, self.CL,
                              self.CPV, self.B, self.CM, self.COLBURN)

        self.UBL = UBLDef(
            'C', self.charLength, self.weather.staTemp[0], maxdx, self.geoParam.dayBLHeight, self.geoParam.nightBLHeight)

        # Defining road
        emis = 0.93
        asphalt = Material(self.kRoad, self.cRoad, 'asphalt')
        road_T_init = 293.
        road_horizontal = 1
        # fraction of surface vegetation coverage
        road_veg_coverage = min(self.vegCover/(1-self.bldDensity), 1.)

        # define road layers
        road_layer_num = int(math.ceil(self.d_road/0.05))
        # 0.5/0.05 ~ 10 x 1 matrix of 0.05 thickness
        thickness_vector = [0.05 for r in range(road_layer_num)]
        material_vector = [asphalt for r in range(road_layer_num)]

        self.road = Element(self.alb_road, emis, thickness_vector, material_vector, road_veg_coverage,
                            road_T_init, road_horizontal, name="urban_road")

        self.rural = copy.deepcopy(self.road)
        self.rural.vegCoverage = self.rurVegCover
        self.rural._name = "rural_road"

        # Reference site class (also include VDM)
        self.RSM = RSMDef(self.lat, self.lon, self.GMT, self.h_obs,
                          self.weather.staTemp[0], self.weather.staPres[0], self.geoParam, self.z_meso_dir_path)
        self.USM = RSMDef(self.lat, self.lon, self.GMT, self.bldHeight/10.,
                          self.weather.staTemp[0], self.weather.staPres[0], self.geoParam, self.z_meso_dir_path)

        T_init = self.weather.staTemp[0]
        H_init = self.weather.staHum[0]

        self.UCM = UCMDef(self.bldHeight, self.bldDensity, self.verToHor, self.treeCoverage, self.sensAnth, self.latAnth, T_init, H_init,
                          self.weather.staUmod[0], self.geoParam, self.r_glaze_total, self.SHGC_total, self.alb_wall_total, self.road)
        self.UCM.h_mix = self.h_mix

        # Define Road Element & buffer to match ground temperature depth
        roadMat, newthickness = procMat(self.road, self.MAXTHICKNESS, self.MINTHICKNESS)

        for i in range(self.nSoil):
            # if soil depth is greater then the thickness of the road
            # we add new slices of soil at max thickness until road is greater or equal

            is_soildepth_equal = self.is_near_zero(self.depth_soil[i][0] - sum(newthickness), 1e-15)

            if is_soildepth_equal or (self.depth_soil[i][0] > sum(newthickness)):
                while self.depth_soil[i][0] > sum(newthickness):
                    newthickness.append(self.MAXTHICKNESS)
                    roadMat.append(self.SOIL)
                self.soilindex1 = i
                break

        self.road = Element(self.road.albedo, self.road.emissivity, newthickness, roadMat,
                            self.road.vegCoverage, self.road.layerTemp[0], self.road.horizontal, self.road._name)

        # Define Rural Element
        ruralMat, newthickness = procMat(self.rural, self.MAXTHICKNESS, self.MINTHICKNESS)

        for i in range(self.nSoil):
            # if soil depth is greater then the thickness of the road
            # we add new slices of soil at max thickness until road is greater or equal

            is_soildepth_equal = self.is_near_zero(self.depth_soil[i][0] - sum(newthickness), 1e-15)

            if is_soildepth_equal or (self.depth_soil[i][0] > sum(newthickness)):
                while self.depth_soil[i][0] > sum(newthickness):
                    newthickness.append(self.MAXTHICKNESS)
                    ruralMat.append(self.SOIL)

                self.soilindex2 = i
                break

        self.rural = Element(self.rural.albedo, self.rural.emissivity, newthickness,
                             ruralMat, self.rural.vegCoverage, self.rural.layerTemp[0], self.rural.horizontal, self.rural._name)


Instruction:
Can you generate the documentation for the following Python 3 function
def hvac_autosize(self):

        for i in range(len(self.BEM)):
            if self.is_near_zero(self.autosize) == False:
                self.BEM[i].building.coolCap = 9999.
                self.BEM[i].building.heatCap = 9999.

Response: A method to set the cooling and heating cap of all the related resources.


Instruction:
How would you explain what the following Python 3 function does
def simulate(self):

        self.N = int(self.simTime.days * 24)       # total number of hours in simulation
        n = 0                                      # weather time step counter
        self.ph = self.simTime.dt/3600.            # dt (simulation time step) in hours

        # Data dump variables
        time = range(self.N)

        self.WeatherData = [None for x in range(self.N)]
        self.UCMData = [None for x in range(self.N)]
        self.UBLData = [None for x in range(self.N)]
        self.RSMData = [None for x in range(self.N)]
        self.USMData = [None for x in range(self.N)]

        print('\nSimulating new temperature and humidity values for {} days from {}/{}.\n'.format(
            int(self.nDay), int(self.Month), int(self.Day)))
        self.logger.info("Start simulation")

        for it in range(1, self.simTime.nt, 1):  # for every simulation time-step (i.e 5 min) defined by uwg
            # Update water temperature (estimated)
            if self.nSoil < 3: # correction to original matlab code
                # for BUBBLE/CAPITOUL/Singapore only
                self.forc.deepTemp = sum(self.forcIP.temp)/float(len(self.forcIP.temp))
                self.forc.waterTemp = sum(
                    self.forcIP.temp)/float(len(self.forcIP.temp)) - 10.      # for BUBBLE/CAPITOUL/Singapore only
            else:
                # soil temperature by depth, by month
                self.forc.deepTemp = self.Tsoil[self.soilindex1][self.simTime.month-1]
                self.forc.waterTemp = self.Tsoil[2][self.simTime.month-1]

            # There's probably a better way to update the weather...
            self.simTime.UpdateDate()

            self.logger.info("\n{0} m={1}, d={2}, h={3}, s={4}".format(
                __name__, self.simTime.month, self.simTime.day, self.simTime.secDay/3600., self.simTime.secDay))

            # simulation time increment raised to weather time step
            self.ceil_time_step = int(math.ceil(it * self.ph))-1
            # minus one to be consistent with forcIP list index
            # Updating forcing instance
            # horizontal Infrared Radiation Intensity (W m-2)
            self.forc.infra = self.forcIP.infra[self.ceil_time_step]
            # wind speed (m s-1)
            self.forc.wind = max(self.forcIP.wind[self.ceil_time_step], self.geoParam.windMin)
            self.forc.uDir = self.forcIP.uDir[self.ceil_time_step]          # wind direction
            # specific humidty (kg kg-1)
            self.forc.hum = self.forcIP.hum[self.ceil_time_step]
            self.forc.pres = self.forcIP.pres[self.ceil_time_step]          # Pressure (Pa)
            self.forc.temp = self.forcIP.temp[self.ceil_time_step]          # air temperature (C)
            self.forc.rHum = self.forcIP.rHum[self.ceil_time_step]          # Relative humidity (%)
            self.forc.prec = self.forcIP.prec[self.ceil_time_step]          # Precipitation (mm h-1)
            # horizontal solar diffuse radiation (W m-2)
            self.forc.dif = self.forcIP.dif[self.ceil_time_step]
            # normal solar direct radiation (W m-2)
            self.forc.dir = self.forcIP.dir[self.ceil_time_step]
            # Canyon humidity (absolute) same as rural
            self.UCM.canHum = copy.copy(self.forc.hum)

            # Update solar flux
            self.solar = SolarCalcs(self.UCM, self.BEM, self.simTime,
                                    self.RSM, self.forc, self.geoParam, self.rural)
            self.rural, self.UCM, self.BEM = self.solar.solarcalcs()

            # Update building & traffic schedule
            # Assign day type (1 = weekday, 2 = sat, 3 = sun/other)
            if self.is_near_zero(self.simTime.julian % 7):
                self.dayType = 3                                        # Sunday
            elif self.is_near_zero(self.simTime.julian % 7 - 6.):
                self.dayType = 2                                        # Saturday
            else:
                self.dayType = 1                                        # Weekday

            # Update anthropogenic heat load for each hour (building & UCM)
            self.UCM.sensAnthrop = self.sensAnth * (self.SchTraffic[self.dayType-1][self.simTime.hourDay])

            # Update the energy components for building types defined in initialize.uwg
            for i in range(len(self.BEM)):
                # Set temperature
                self.BEM[i].building.coolSetpointDay = self.Sch[i].Cool[self.dayType -
                                                                        1][self.simTime.hourDay] + 273.15  # add from temperature schedule for cooling
                self.BEM[i].building.coolSetpointNight = self.BEM[i].building.coolSetpointDay
                self.BEM[i].building.heatSetpointDay = self.Sch[i].Heat[self.dayType -
                                                                        1][self.simTime.hourDay] + 273.15  # add from temperature schedule for heating
                self.BEM[i].building.heatSetpointNight = self.BEM[i].building.heatSetpointDay

                # Internal Heat Load Schedule (W/m^2 of floor area for Q)
                self.BEM[i].Elec = self.Sch[i].Qelec * self.Sch[i].Elec[self.dayType -
                                                                        1][self.simTime.hourDay]      # Qelec x elec fraction for day
                self.BEM[i].Light = self.Sch[i].Qlight * self.Sch[i].Light[self.dayType -
                                                                           1][self.simTime.hourDay]    # Qlight x light fraction for day
                self.BEM[i].Nocc = self.Sch[i].Nocc * self.Sch[i].Occ[self.dayType -
                                                                      1][self.simTime.hourDay]        # Number of occupants x occ fraction for day
                # Sensible Q occupant * fraction occupant sensible Q * number of occupants
                self.BEM[i].Qocc = self.sensOcc * (1 - self.LatFOcc) * self.BEM[i].Nocc

                # SWH and ventilation schedule
                self.BEM[i].SWH = self.Sch[i].Vswh * self.Sch[i].SWH[self.dayType -
                                                                     1][self.simTime.hourDay]          # litres per hour x SWH fraction for day
                # m^3/s/m^2 of floor
                self.BEM[i].building.vent = self.Sch[i].Vent
                self.BEM[i].Gas = self.Sch[i].Qgas * self.Sch[i].Gas[self.dayType -
                                                                     1][self.simTime.hourDay]          # Gas Equip Schedule, per m^2 of floor

                # This is quite messy, should update
                # Update internal heat and corresponding fractional loads
                intHeat = self.BEM[i].Light + self.BEM[i].Elec + self.BEM[i].Qocc
                # W/m2 from light, electricity, occupants
                self.BEM[i].building.intHeatDay = intHeat
                self.BEM[i].building.intHeatNight = intHeat
                # fraction of radiant heat from light and equipment of whole internal heat
                self.BEM[i].building.intHeatFRad = (
                    self.RadFLight * self.BEM[i].Light + self.RadFEquip * self.BEM[i].Elec) / intHeat
                # fraction of latent heat (from occupants) of whole internal heat
                self.BEM[i].building.intHeatFLat = self.LatFOcc * \
                    self.sensOcc * self.BEM[i].Nocc/intHeat

                # Update envelope temperature layers
                self.BEM[i].T_wallex = self.BEM[i].wall.layerTemp[0]
                self.BEM[i].T_wallin = self.BEM[i].wall.layerTemp[-1]
                self.BEM[i].T_roofex = self.BEM[i].roof.layerTemp[0]
                self.BEM[i].T_roofin = self.BEM[i].roof.layerTemp[-1]

            # Update rural heat fluxes & update vertical diffusion model (VDM)
            self.rural.infra = self.forc.infra - self.rural.emissivity * self.SIGMA * \
                self.rural.layerTemp[0]**4.    # Infrared radiation from rural road

            self.rural.SurfFlux(self.forc, self.geoParam, self.simTime,
                                self.forc.hum, self.forc.temp, self.forc.wind, 2., 0.)
            self.RSM.VDM(self.forc, self.rural, self.geoParam, self.simTime)

            # Calculate urban heat fluxes, update UCM & UBL
            self.UCM, self.UBL, self.BEM = urbflux(
                self.UCM, self.UBL, self.BEM, self.forc, self.geoParam, self.simTime, self.RSM)
            self.UCM.UCModel(self.BEM, self.UBL.ublTemp, self.forc, self.geoParam)
            self.UBL.UBLModel(self.UCM, self.RSM, self.rural,
                              self.forc, self.geoParam, self.simTime)

            """
            # Experimental code to run diffusion model in the urban area
            # N.B Commented out in python uwg because computed wind speed in
            # urban VDM: y = =0.84*ln((2-x/20)/0.51) results in negative log
            # for building heights >= 40m.

            Uroad = copy.copy(self.UCM.road)
            Uroad.sens = copy.copy(self.UCM.sensHeat)
            Uforc = copy.copy(self.forc)
            Uforc.wind = copy.copy(self.UCM.canWind)
            Uforc.temp = copy.copy(self.UCM.canTemp)
            self.USM.VDM(Uforc,Uroad,self.geoParam,self.simTime)
            """

            self.logger.info("dbT = {}".format(self.UCM.canTemp-273.15))
            if n > 0:
                logging.info("dpT = {}".format(self.UCM.Tdp))
                logging.info("RH  = {}".format(self.UCM.canRHum))

            if self.is_near_zero(self.simTime.secDay % self.simTime.timePrint) and n < self.N:

                self.logger.info("{0} ----sim time step = {1}----\n\n".format(__name__, n))

                self.WeatherData[n] = copy.copy(self.forc)
                _Tdb, _w, self.UCM.canRHum, _h, self.UCM.Tdp, _v = psychrometrics(
                    self.UCM.canTemp, self.UCM.canHum, self.forc.pres)

                self.UBLData[n] = copy.copy(self.UBL)
                self.UCMData[n] = copy.copy(self.UCM)
                self.RSMData[n] = copy.copy(self.RSM)

                self.logger.info("dbT = {}".format(self.UCMData[n].canTemp-273.15))
                self.logger.info("dpT = {}".format(self.UCMData[n].Tdp))
                self.logger.info("RH  = {}".format(self.UCMData[n].canRHum))

                n += 1

Response: Create a new object instance with the given information.


Instruction:
How would you code a function in Python 3 to
write the new EPW file.

Response:
def write_epw(self):
        """ Section 8 - Writing new EPW file
        """
        epw_prec = self.epw_precision  # precision of epw file input

        for iJ in range(len(self.UCMData)):
            # [iJ+self.simTime.timeInitial-8] = increments along every weather timestep in epw
            # [6 to 21]                       = column data of epw
            self.epwinput[iJ+self.simTime.timeInitial-8][6] = "{0:.{1}f}".format(
                self.UCMData[iJ].canTemp - 273.15, epw_prec)  # dry bulb temperature  [?C]
            # dew point temperature [?C]
            self.epwinput[iJ+self.simTime.timeInitial -
                          8][7] = "{0:.{1}f}".format(self.UCMData[iJ].Tdp, epw_prec)
            # relative humidity     [%]
            self.epwinput[iJ+self.simTime.timeInitial -
                          8][8] = "{0:.{1}f}".format(self.UCMData[iJ].canRHum, epw_prec)
            self.epwinput[iJ+self.simTime.timeInitial-8][21] = "{0:.{1}f}".format(
                self.WeatherData[iJ].wind, epw_prec)        # wind speed [m/s]

        # Writing new EPW file
        epw_new_id = open(self.newPathName, "w")

        for i in range(8):
            new_epw_line = '{}\n'.format(reduce(lambda x, y: x+","+y, self._header[i]))
            epw_new_id.write(new_epw_line)

        for i in range(len(self.epwinput)):
            printme = ""
            for ei in range(34):
                printme += "{}".format(self.epwinput[i][ei]) + ','
            printme = printme + "{}".format(self.epwinput[i][ei])
            new_epw_line = "{0}\n".format(printme)
            epw_new_id.write(new_epw_line)

        epw_new_id.close()

        print("New climate file '{}' is generated at {}.".format(
            self.destinationFileName, self.destinationDir))


Instruction:
Create a Python 3 function to
calculate net heat flux and updates element layer temperatures with new values.

Response:
def SurfFlux(self,forc,parameter,simTime,humRef,tempRef,windRef,boundCond,intFlux):
        """ Calculate net heat flux, and update element layer temperatures
        """

        # Calculated per unit area (m^2)
        dens = forc.pres/(1000*0.287042*tempRef*(1.+1.607858*humRef)) # air density (kgd m-3)
        self.aeroCond = 5.8 + 3.7 * windRef         # Convection coef (ref: uwg, eq. 12))

        if (self.horizontal):     # For roof, mass, road
            # Evaporation (m s-1), Film water & soil latent heat
            if not self.is_near_zero(self.waterStorage) and self.waterStorage > 0.0:
                # N.B In the current uwg code, latent heat from evapotranspiration, stagnant water,
                # or anthropogenic sources is not modelled due to the difficulty of validation, and
                # lack of reliability of precipitation data from EPW files.Therefore this condition
                # is never run because all elements have had their waterStorage hardcoded to 0.
                qtsat = self.qsat([self.layerTemp[0]],[forc.pres],parameter)[0]
                eg = self.aeroCond*parameter.colburn*dens*(qtsat-humRef)/parameter.waterDens/parameter.cp
                self.waterStorage = min(self.waterStorage + simTime.dt*(forc.prec-eg),parameter.wgmax)
                self.waterStorage = max(self.waterStorage,0.) # (m)
            else:
                eg = 0.
            soilLat = eg*parameter.waterDens*parameter.lv

            # Winter, no veg
            if simTime.month < parameter.vegStart and simTime.month > parameter.vegEnd:
                self.solAbs = (1.-self.albedo)*self.solRec # (W m-2)
                vegLat = 0.
                vegSens = 0.
            else:    # Summer, veg
                self.solAbs = ((1.-self.vegCoverage)*(1.-self.albedo)+self.vegCoverage*(1.-parameter.vegAlbedo))*self.solRec
                vegLat = self.vegCoverage*parameter.grassFLat*(1.-parameter.vegAlbedo)*self.solRec
                vegSens = self.vegCoverage*(1.-parameter.grassFLat)*(1.-parameter.vegAlbedo)*self.solRec

            self.lat = soilLat + vegLat
            # Sensible & net heat flux
            self.sens = vegSens + self.aeroCond*(self.layerTemp[0]-tempRef)
            self.flux = -self.sens + self.solAbs + self.infra - self.lat # (W m-2)

        else:               # For vertical surfaces (wall)
            self.solAbs = (1.-self.albedo)*self.solRec
            self.lat = 0.

            # Sensible & net heat flux
            self.sens = self.aeroCond*(self.layerTemp[0]-tempRef)
            self.flux = -self.sens + self.solAbs + self.infra - self.lat # (W m-2)

        self.layerTemp = self.Conduction(simTime.dt, self.flux, boundCond, forc.deepTemp, intFlux)
        self.T_ext = self.layerTemp[0]
        self.T_int = self.layerTemp[-1]


Instruction:
Given the following Python 3 function, write the documentation
def Conduction(self, dt, flx1, bc, temp2, flx2):
        t = self.layerTemp          # vector of layer temperatures (K)
        hc = self.layerVolHeat      # vector of layer volumetric heat (J m-3 K-1)
        tc = self.layerThermalCond  # vector of layer thermal conductivities (W m-1 K-1)
        d = self.layerThickness     # vector of layer thicknesses (m)

        # flx1                      : net heat flux on surface
        # bc                        : boundary condition parameter (1 or 2)
        # temp2                     : deep soil temperature (avg of air temperature)
        # flx2                      : surface flux (sum of absorbed, emitted, etc.)

        fimp = 0.5                  # implicit coefficient
        fexp = 0.5                  # explicit coefficient
        num = len(t)                # number of layers

        # Mean thermal conductivity over distance between 2 layers (W/mK)
        tcp = [0 for x in range(num)]
        # Thermal capacity times layer depth (J/m2K)
        hcp = [0 for x in range(num)]
        # lower, main, and upper diagonals
        za = [[0 for y in range(3)] for x in range(num)]
        # RHS
        zy = [0 for x in range(num)]

        #--------------------------------------------------------------------------
        # Define the column vectors for heat capactiy and conductivity
        hcp[0] = hc[0] * d[0]
        for j in range(1,num):
            tcp[j] = 2. / (d[j-1] / tc[j-1] + d[j] / tc[j])
            hcp[j] = hc[j] * d[j]

        #--------------------------------------------------------------------------
        # Define the first row of za matrix, and RHS column vector
        za[0][0] = 0.
        za[0][1] = hcp[0]/dt + fimp*tcp[1]
        za[0][2] = -fimp*tcp[1]
        zy[0] = hcp[0]/dt*t[0] - fexp*tcp[1]*(t[0]-t[1]) + flx1

        #--------------------------------------------------------------------------
        # Define other rows
        for j in range(1,num-1):
          za[j][0] = fimp*(-tcp[j])
          za[j][1] = hcp[j]/dt + fimp*(tcp[j]+tcp[j+1])
          za[j][2] = fimp*(-tcp[j+1])
          zy[j] = hcp[j]/dt * t[j] + fexp * \
            (tcp[j]*t[j-1] - tcp[j]*t[j] - tcp[j+1]*t[j] + tcp[j+1]*t[j+1])

        #--------------------------------------------------------------------------
        # Boundary conditions
        if self.is_near_zero(bc-1.): # heat flux
            za[num-1][0] = fimp * (-tcp[num-1])
            za[num-1][1] = hcp[num-1]/dt + fimp*tcp[num-1]
            za[num-1][2] = 0.
            zy[num-1] = hcp[num-1]/dt*t[num-1] + fexp*tcp[num-1]*(t[num-2]-t[num-1]) + flx2
        elif self.is_near_zero(bc-2.): # deep-temperature
            za[num-1][0] = 0.
            za[num-1][1] = 1.
            za[num-1][2] = 0.
            zy[num-1] = temp2
        else:
            raise Exception(self.CONDUCTION_INPUT_MSG)

        #--------------------------------------------------------------------------

        zx = self.invert(num,za,zy)
        #t(:) = zx(:);
        return zx

Response: Solve the conductance of heat based on the element layers.


Instruction:
Can you create a Python 3 function that
calculates the QSAT vector of saturation humidity from a set of temperature and pressure.

Response:
def qsat(self,temp,pres,parameter):
        """
        Calculate (qsat_lst) vector of saturation humidity from:
            temp = vector of element layer temperatures
            pres = pressure (at current timestep).
        """
        gamw = (parameter.cl - parameter.cpv) / parameter.rv
        betaw = (parameter.lvtt/parameter.rv) + (gamw * parameter.tt)
        alpw = math.log(parameter.estt) + (betaw /parameter.tt) + (gamw * math.log(parameter.tt))
        work2 = parameter.r/parameter.rv
        foes_lst = [0 for i in range(len(temp))]
        work1_lst = [0 for i in range(len(temp))]
        qsat_lst = [0 for i in range(len(temp))]

        for i in range(len(temp)):
          # saturation vapor pressure
          foes_lst[i] = math.exp( alpw - betaw/temp[i] - gamw*math.log(temp[i])  )
          work1_lst[i] = foes_lst[i]/pres[i]
          # saturation humidity
          qsat_lst[i] = work2*work1_lst[i] / (1. + (work2-1.) * work1_lst[i])

        return qsat_lst


Instruction:
Make a summary of the following Python 3 code
def readDOE(serialize_output=True):

    #Nested, nested lists of Building, SchDef, BEMDef objects
    refDOE   = [[[None]*16 for k_ in range(3)] for j_ in range(16)]                #refDOE(16,3,16) = Building
    Schedule = [[[None]*16 for k_ in range(3)] for j_ in range(16)]                #Schedule (16,3,16) = SchDef
    refBEM   = [[[None]*16 for k_ in range(3)] for j_ in range(16)]                #refBEM (16,3,16) = BEMDef

    #Purpose: Loop through every DOE reference csv and extract building data
    #Nested loop = 16 types, 3 era, 16 zones = time complexity O(n*m*k) = 768
    for i in range(16):

        #i = 16 types of buildings
        #print "\tType: {} @i={}".format(BLDTYPE[i], i)

        # Read building summary (Sheet 1)
        file_doe_name_bld = os.path.join("{}".format(DIR_DOE_PATH), "BLD{}".format(i+1),"BLD{}_BuildingSummary.csv".format(i+1))
        list_doe1 = read_csv(file_doe_name_bld)
        #listof(listof 3 era values)
        nFloor      = str2fl(list_doe1[3][3:6])      # Number of Floors, this will be list of floats and str if "basement"
        glazing     = str2fl(list_doe1[4][3:6])      # [?] Total
        hCeiling    = str2fl(list_doe1[5][3:6])      # [m] Ceiling height
        ver2hor     = str2fl(list_doe1[7][3:6])      # Wall to Skin Ratio
        AreaRoof    = str2fl(list_doe1[8][3:6])      # [m2] Gross Dimensions - Total area

        # Read zone summary (Sheet 2)
        file_doe_name_zone = os.path.join("{}".format(DIR_DOE_PATH), "BLD{}".format(i+1),"BLD{}_ZoneSummary.csv".format(i+1))
        list_doe2 = read_csv(file_doe_name_zone)
        #listof(listof 3 eras)
        AreaFloor   = str2fl([list_doe2[2][5],list_doe2[3][5],list_doe2[4][5]])       # [m2]
        Volume      = str2fl([list_doe2[2][6],list_doe2[3][6],list_doe2[4][6]])       # [m3]
        AreaWall    = str2fl([list_doe2[2][8],list_doe2[3][8],list_doe2[4][8]])       # [m2]
        AreaWindow  = str2fl([list_doe2[2][9],list_doe2[3][9],list_doe2[4][9]])       # [m2]
        Occupant    = str2fl([list_doe2[2][11],list_doe2[3][11],list_doe2[4][11]])    # Number of People
        Light       = str2fl([list_doe2[2][12],list_doe2[3][12],list_doe2[4][12]])    # [W/m2]
        Elec        = str2fl([list_doe2[2][13],list_doe2[3][13],list_doe2[4][13]])    # [W/m2] Electric Plug and Process
        Gas         = str2fl([list_doe2[2][14],list_doe2[3][14],list_doe2[4][14]])    # [W/m2] Gas Plug and Process
        SHW         = str2fl([list_doe2[2][15],list_doe2[3][15],list_doe2[4][15]])    # [Litres/hr] Peak Service Hot Water
        Vent        = str2fl([list_doe2[2][17],list_doe2[3][17],list_doe2[4][17]])    # [L/s/m2] Ventilation
        Infil       = str2fl([list_doe2[2][20],list_doe2[3][20],list_doe2[4][20]])    # Air Changes Per Hour (ACH) Infiltration

        # Read location summary (Sheet 3)
        file_doe_name_location = os.path.join("{}".format(DIR_DOE_PATH), "BLD{}".format(i+1),"BLD{}_LocationSummary.csv".format(i+1))
        list_doe3 = read_csv(file_doe_name_location)
        #(listof (listof 3 eras (listof 16 climate types)))
        TypeWall    = [list_doe3[3][4:20],list_doe3[14][4:20],list_doe3[25][4:20]]            # Construction type
        RvalWall    = str2fl([list_doe3[4][4:20],list_doe3[15][4:20],list_doe3[26][4:20]])     # [m2*K/W] R-value
        TypeRoof    = [list_doe3[5][4:20],list_doe3[16][4:20],list_doe3[27][4:20]]            # Construction type
        RvalRoof    = str2fl([list_doe3[6][4:20],list_doe3[17][4:20],list_doe3[28][4:20]])     # [m2*K/W] R-value
        Uwindow     = str2fl([list_doe3[7][4:20],list_doe3[18][4:20],list_doe3[29][4:20]])     # [W/m2*K] U-factor
        SHGC        = str2fl([list_doe3[8][4:20],list_doe3[19][4:20],list_doe3[30][4:20]])     # [-] coefficient
        HVAC        = str2fl([list_doe3[9][4:20],list_doe3[20][4:20],list_doe3[31][4:20]])     # [kW] Air Conditioning
        HEAT        = str2fl([list_doe3[10][4:20],list_doe3[21][4:20],list_doe3[32][4:20]])    # [kW] Heating
        COP         = str2fl([list_doe3[11][4:20],list_doe3[22][4:20],list_doe3[33][4:20]])    # [-] Air Conditioning COP
        EffHeat     = str2fl([list_doe3[12][4:20],list_doe3[23][4:20],list_doe3[34][4:20]])    # [%] Heating Efficiency
        FanFlow     = str2fl([list_doe3[13][4:20],list_doe3[24][4:20],list_doe3[35][4:20]])    # [m3/s] Fan Max Flow Rate

        # Read Schedules (Sheet 4)
        file_doe_name_schedules = os.path.join("{}".format(DIR_DOE_PATH), "BLD{}".format(i+1),"BLD{}_Schedules.csv".format(i+1))
        list_doe4 = read_csv(file_doe_name_schedules)

        #listof(listof weekday, sat, sun (list of 24 fractions)))
        SchEquip    = str2fl([list_doe4[1][6:30],list_doe4[2][6:30],list_doe4[3][6:30]])      # Equipment Schedule 24 hrs
        SchLight    = str2fl([list_doe4[4][6:30],list_doe4[5][6:30],list_doe4[6][6:30]])      # Light Schedule 24 hrs; Wkday=Sat=Sun=Hol
        SchOcc      = str2fl([list_doe4[7][6:30],list_doe4[8][6:30],list_doe4[9][6:30]])      # Occupancy Schedule 24 hrs
        SetCool     = str2fl([list_doe4[10][6:30],list_doe4[11][6:30],list_doe4[12][6:30]])   # Cooling Setpoint Schedule 24 hrs
        SetHeat     = str2fl([list_doe4[13][6:30],list_doe4[14][6:30],list_doe4[15][6:30]])   # Heating Setpoint Schedule 24 hrs; summer design
        SchGas      = str2fl([list_doe4[16][6:30],list_doe4[17][6:30],list_doe4[18][6:30]])   # Gas Equipment Schedule 24 hrs; wkday=sat
        SchSWH      = str2fl([list_doe4[19][6:30],list_doe4[20][6:30],list_doe4[21][6:30]])   # Solar Water Heating Schedule 24 hrs; wkday=summerdesign, sat=winterdesgin

        for j in range(3):

            # j = 3 built eras
            #print"\tEra: {} @j={}".format(BUILTERA[j], j)

            for k in range(16):

                # k = 16 climate zones
                #print "\tClimate zone: {} @k={}".format(ZONETYPE[k], k)

                B = Building(
                    hCeiling[j],                        # floorHeight by era
                    1,                                  # intHeatNight
                    1,                                  # intHeatDay
                    0.1,                                # intHeatFRad
                    0.1,                                # intHeatFLat
                    Infil[j],                           # infil (ACH) by era
                    Vent[j]/1000.,                      # vent (m^3/s/m^2) by era, converted from liters
                    glazing[j],                         # glazing ratio by era
                    Uwindow[j][k],                      # uValue by era, by climate type
                    SHGC[j][k],                         # SHGC, by era, by climate type
                    'AIR',                              # cooling condensation system type: AIR, WATER
                    COP[j][k],                          # cop by era, climate type
                    297,                                # coolSetpointDay = 24 C
                    297,                                # coolSetpointNight
                    293,                                # heatSetpointDay = 20 C
                    293,                                # heatSetpointNight
                    (HVAC[j][k]*1000.0)/AreaFloor[j],   # coolCap converted to W/m2 by era, climate type
                    EffHeat[j][k],                      # heatEff by era, climate type
                    293)                                # initialTemp at 20 C

                #Not defined in the constructor
                B.heatCap = (HEAT[j][k]*1000.0)/AreaFloor[j]         # heating Capacity converted to W/m2 by era, climate type
                B.Type = BLDTYPE[i]
                B.Era = BUILTERA[j]
                B.Zone = ZONETYPE[k]
                refDOE[i][j][k] = B

                # Define wall, mass(floor), roof
                # Reference from E+ for conductivity, thickness (reference below)

                # Material: (thermalCond, volHeat = specific heat * density)
                Concrete = Material (1.311, 836.8 * 2240,"Concrete")
                Insulation = Material (0.049, 836.8 * 265.0, "Insulation")
                Gypsum = Material (0.16, 830.0 * 784.9, "Gypsum")
                Wood = Material (0.11, 1210.0 * 544.62, "Wood")
                Stucco = Material(0.6918,  837.0 * 1858.0, "Stucco")

                # Wall (1 in stucco, concrete, insulation, gypsum)
                # Check TypWall by era, by climate
                if TypeWall[j][k] == "MassWall":
                    #Construct wall based on R value of Wall from refDOE and properties defined above
                    # 1" stucco, 8" concrete, tbd insulation, 1/2" gypsum
                    Rbase = 0.271087 # R val based on stucco, concrete, gypsum
                    Rins = RvalWall[j][k] - Rbase #find insulation value
                    D_ins = Rins * Insulation.thermalCond # depth of ins from m2*K/W * W/m*K = m
                    if D_ins > 0.01:
                        thickness = [0.0254,0.0508,0.0508,0.0508,0.0508,D_ins,0.0127]
                        layers = [Stucco,Concrete,Concrete,Concrete,Concrete,Insulation,Gypsum]
                    else:
                        #if it's less then 1 cm don't include in layers
                        thickness = [0.0254,0.0508,0.0508,0.0508,0.0508,0.0127]
                        layers = [Stucco,Concrete,Concrete,Concrete,Concrete,Gypsum]

                    wall = Element(0.08,0.92,thickness,layers,0.,293.,0.,"MassWall")

                    # If mass wall, assume mass floor (4" concrete)
                    # Mass (assume 4" concrete);
                    alb = 0.2
                    emis = 0.9
                    thickness = [0.054,0.054]
                    concrete = Material (1.31, 2240.0*836.8)
                    mass = Element(alb,emis,thickness,[concrete,concrete],0,293,1,"MassFloor")

                elif TypeWall[j][k] == "WoodFrame":
                    # 0.01m wood siding, tbd insulation, 1/2" gypsum
                    Rbase = 0.170284091    # based on wood siding, gypsum
                    Rins = RvalWall[j][k] - Rbase
                    D_ins = Rins * Insulation.thermalCond #depth of insulatino

                    if D_ins > 0.01:
                        thickness = [0.01,D_ins,0.0127]
                        layers = [Wood,Insulation,Gypsum]
                    else:
                        thickness = [0.01,0.0127]
                        layers = [Wood,Gypsum]

                    wall = Element(0.22,0.92,thickness,layers,0.,293.,0.,"WoodFrameWall")

                    # If wood frame wall, assume wooden floor
                    alb = 0.2
                    emis = 0.9
                    thickness = [0.05,0.05]
                    wood = Material(1.31, 2240.0*836.8)
                    mass = Element(alb,emis,thickness,[wood,wood],0.,293.,1.,"WoodFloor")

                elif TypeWall[j][k] == "SteelFrame":
                    # 1" stucco, 8" concrete, tbd insulation, 1/2" gypsum
                    Rbase = 0.271087 # based on stucco, concrete, gypsum
                    Rins = RvalWall[j][k] - Rbase
                    D_ins = Rins * Insulation.thermalCond
                    if D_ins > 0.01:
                        thickness = [0.0254,0.0508,0.0508,0.0508,0.0508,D_ins,0.0127]
                        layers = [Stucco,Concrete,Concrete,Concrete,Concrete,Insulation,Gypsum]
                    else:    # If insulation is too thin, assume no insulation
                        thickness = [0.0254,0.0508,0.0508,0.0508,0.0508,0.0127]
                        layers = [Stucco,Concrete,Concrete,Concrete,Concrete,Gypsum]
                    wall = Element(0.15,0.92,thickness,layers,0.,293.,0.,"SteelFrame")

                    # If mass wall, assume mass foor
                    # Mass (assume 4" concrete),
                    alb = 0.2
                    emis = 0.93
                    thickness = [0.05,0.05]
                    mass = Element(alb,emis,thickness,[Concrete,Concrete],0.,293.,1.,"MassFloor")

                elif TypeWall[j][k] == "MetalWall":
                    # metal siding, insulation, 1/2" gypsum
                    alb = 0.2
                    emis = 0.9
                    D_ins = max((RvalWall[j][k] * Insulation.thermalCond)/2, 0.01) #use derived insul thickness or 0.01 based on max
                    thickness = [D_ins,D_ins,0.0127]
                    materials = [Insulation,Insulation,Gypsum]
                    wall = Element(alb,emis,thickness,materials,0,293,0,"MetalWall")

                    # Mass (assume 4" concrete);
                    alb = 0.2
                    emis = 0.9
                    thickness = [0.05, 0.05]
                    concrete = Material(1.31, 2240.0*836.8)
                    mass = Element(alb,emis,thickness,[concrete,concrete],0.,293.,1.,"MassFloor")

                # Roof
                if TypeRoof[j][k] == "IEAD": #Insulation Entirely Above Deck
                    # IEAD-> membrane, insulation, decking
                     alb = 0.2
                     emis = 0.93
                     D_ins = max(RvalRoof[j][k] * Insulation.thermalCond/2.,0.01);
                     roof = Element(alb,emis,[D_ins,D_ins],[Insulation,Insulation],0.,293.,0.,"IEAD")

                elif TypeRoof[j][k] == "Attic":
                    # IEAD-> membrane, insulation, decking
                    alb = 0.2
                    emis = 0.9
                    D_ins = max(RvalRoof[j][k] * Insulation.thermalCond/2.,0.01)
                    roof = Element(alb,emis,[D_ins,D_ins],[Insulation,Insulation],0.,293.,0.,"Attic")

                elif TypeRoof[j][k] == "MetalRoof":
                    # IEAD-> membrane, insulation, decking
                    alb = 0.2
                    emis = 0.9
                    D_ins = max(RvalRoof[j][k] * Insulation.thermalCond/2.,0.01)
                    roof = Element(alb,emis,[D_ins,D_ins],[Insulation,Insulation],0.,293.,0.,"MetalRoof")

                # Define bulding energy model, set fraction of the urban floor space of this typology to zero
                refBEM[i][j][k] = BEMDef(B, mass, wall, roof, 0.0)
                refBEM[i][j][k].building.FanMax = FanFlow[j][k] # max fan flow rate (m^3/s) per DOE

                Schedule[i][j][k] = SchDef()

                Schedule[i][j][k].Elec = SchEquip   # 3x24 matrix of schedule for fraction electricity (WD,Sat,Sun)
                Schedule[i][j][k].Light = SchLight  # 3x24 matrix of schedule for fraction light (WD,Sat,Sun)
                Schedule[i][j][k].Gas = SchGas      # 3x24 matrix of schedule for fraction gas (WD,Sat,Sun)
                Schedule[i][j][k].Occ = SchOcc      # 3x24 matrix of schedule for fraction occupancy (WD,Sat,Sun)
                Schedule[i][j][k].Cool = SetCool    # 3x24 matrix of schedule for fraction cooling temp (WD,Sat,Sun)
                Schedule[i][j][k].Heat = SetHeat    # 3x24 matrix of schedule for fraction heating temp (WD,Sat,Sun)
                Schedule[i][j][k].SWH = SchSWH      # 3x24 matrix of schedule for fraction SWH (WD,Sat,Sun

                Schedule[i][j][k].Qelec = Elec[j]                   # W/m^2 (max) for electrical plug process
                Schedule[i][j][k].Qlight = Light[j]                 # W/m^2 (max) for light
                Schedule[i][j][k].Nocc = Occupant[j]/AreaFloor[j]   # Person/m^2
                Schedule[i][j][k].Qgas = Gas[j]                     # W/m^2 (max) for gas
                Schedule[i][j][k].Vent = Vent[j]/1000.0             # m^3/m^2 per person
                Schedule[i][j][k].Vswh = SHW[j]/AreaFloor[j]        # litres per hour per m^2 of floor

    # if not test serialize refDOE,refBEM,Schedule and store in resources
    if serialize_output:

        # create a binary file for serialized obj
        pkl_file_path = os.path.join(DIR_CURR,'refdata','readDOE.pkl')
        pickle_readDOE = open(pkl_file_path, 'wb')

        # dump in ../resources
        # Pickle objects, protocol 1 b/c binary file
        pickle.dump(refDOE, pickle_readDOE,1)
        pickle.dump(refBEM, pickle_readDOE,1)
        pickle.dump(Schedule, pickle_readDOE,1)

        pickle_readDOE.close()

    return refDOE, refBEM, Schedule

Response: Read all DOE data and return a list of dicts.


Instruction:
Given the following Python 3 function, write the documentation
def readPlist(pathOrFile):
    didOpen = False
    result = None
    if isinstance(pathOrFile, (bytes, unicode)):
        pathOrFile = open(pathOrFile, 'rb')
        didOpen = True
    try:
        reader = PlistReader(pathOrFile)
        result = reader.parse()
    except NotBinaryPlistException as e:
        try:
            pathOrFile.seek(0)
            result = None
            if hasattr(plistlib, 'loads'):
                contents = None
                if isinstance(pathOrFile, (bytes, unicode)):
                    with open(pathOrFile, 'rb') as f:
                        contents = f.read()
                else:
                    contents = pathOrFile.read()
                result = plistlib.loads(contents)
            else:
                result = plistlib.readPlist(pathOrFile)
            result = wrapDataObject(result, for_binary=True)
        except Exception as e:
            raise InvalidPlistException(e)
    finally:
        if didOpen:
            pathOrFile.close()
    return result

Response: Reads a single item from a plist file.


Instruction:
Make a summary of the following Python 3 code
def getSizedInteger(self, data, byteSize, as_number=False):
        result = 0
        if byteSize == 0:
            raise InvalidPlistException("Encountered integer with byte size of 0.")
        # 1, 2, and 4 byte integers are unsigned
        elif byteSize == 1:
            result = unpack('>B', data)[0]
        elif byteSize == 2:
            result = unpack('>H', data)[0]
        elif byteSize == 4:
            result = unpack('>L', data)[0]
        elif byteSize == 8:
            if as_number:
                result = unpack('>q', data)[0]
            else:
                result = unpack('>Q', data)[0]
        elif byteSize <= 16:
            # Handle odd-sized or integers larger than 8 bytes
            # Don't naively go over 16 bytes, in order to prevent infinite loops.
            result = 0
            if hasattr(int, 'from_bytes'):
                result = int.from_bytes(data, 'big')
            else:
                for byte in data:
                    if not isinstance(byte, int): # Python3.0-3.1.x return ints, 2.x return str
                        byte = unpack_from('>B', byte)[0]
                    result = (result << 8) | byte
        else:
            raise InvalidPlistException("Encountered integer longer than 16 bytes.")
        return result

Response: Returns the integer in bytes of size byteSize.


Instruction:
Can you generate the documentation for the following Python 3 function
def writeRoot(self, root):
        output = self.header
        wrapped_root = self.wrapRoot(root)
        self.computeOffsets(wrapped_root, asReference=True, isRoot=True)
        self.trailer = self.trailer._replace(**{'objectRefSize':self.intSize(len(self.computedUniques))})
        self.writeObjectReference(wrapped_root, output)
        output = self.writeObject(wrapped_root, output, setReferencePosition=True)

        # output size at this point is an upper bound on how big the
        # object reference offsets need to be.
        self.trailer = self.trailer._replace(**{
            'offsetSize':self.intSize(len(output)),
            'offsetCount':len(self.computedUniques),
            'offsetTableOffset':len(output),
            'topLevelObjectNumber':0
            })

        output = self.writeOffsetTable(output)
        output += pack('!xxxxxxBBQQQ', *self.trailer)
        self.file.write(output)

Response: Write the root object to the file.


Instruction:
Given the following Python 3 function, write the documentation
def writeObjectReference(self, obj, output):
        position = self.positionOfObjectReference(obj)
        if position is None:
            self.writtenReferences[obj] = len(self.writtenReferences)
            output += self.binaryInt(len(self.writtenReferences) - 1, byteSize=self.trailer.objectRefSize)
            return (True, output)
        else:
            output += self.binaryInt(position, byteSize=self.trailer.objectRefSize)
            return (False, output)

Response: Tries to write an object reference to the output. Returns a tuple of whether the object was a new reference or not.


Instruction:
Can you generate the documentation for the following Python 3 function
def writeObject(self, obj, output, setReferencePosition=False):
        def proc_variable_length(format, length):
            result = b''
            if length > 0b1110:
                result += pack('!B', (format << 4) | 0b1111)
                result = self.writeObject(length, result)
            else:
                result += pack('!B', (format << 4) | length)
            return result

        def timedelta_total_seconds(td):
            # Shim for Python 2.6 compatibility, which doesn't have total_seconds.
            # Make one argument a float to ensure the right calculation.
            return (td.microseconds + (td.seconds + td.days * 24 * 3600) * 10.0**6) / 10.0**6

        if setReferencePosition:
            self.referencePositions[obj] = len(output)

        if obj is None:
            output += pack('!B', 0b00000000)
        elif isinstance(obj, BoolWrapper):
            if obj.value is False:
                output += pack('!B', 0b00001000)
            else:
                output += pack('!B', 0b00001001)
        elif isinstance(obj, Uid):
            size = self.intSize(obj.integer)
            output += pack('!B', (0b1000 << 4) | size - 1)
            output += self.binaryInt(obj.integer)
        elif isinstance(obj, (int, long)):
            byteSize = self.intSize(obj)
            root = math.log(byteSize, 2)
            output += pack('!B', (0b0001 << 4) | int(root))
            output += self.binaryInt(obj, as_number=True)
        elif isinstance(obj, FloatWrapper):
            # just use doubles
            output += pack('!B', (0b0010 << 4) | 3)
            output += self.binaryReal(obj)
        elif isinstance(obj, datetime.datetime):
            try:
                timestamp = (obj - apple_reference_date).total_seconds()
            except AttributeError:
                timestamp = timedelta_total_seconds(obj - apple_reference_date)
            output += pack('!B', 0b00110011)
            output += pack('!d', float(timestamp))
        elif isinstance(obj, Data):
            output += proc_variable_length(0b0100, len(obj))
            output += obj
        elif isinstance(obj, StringWrapper):
            output += proc_variable_length(obj.encodingMarker, len(obj))
            output += obj.encodedValue
        elif isinstance(obj, bytes):
            output += proc_variable_length(0b0101, len(obj))
            output += obj
        elif isinstance(obj, HashableWrapper):
            obj = obj.value
            if isinstance(obj, (set, list, tuple)):
                if isinstance(obj, set):
                    output += proc_variable_length(0b1100, len(obj))
                else:
                    output += proc_variable_length(0b1010, len(obj))

                objectsToWrite = []
                for objRef in sorted(obj) if isinstance(obj, set) else obj:
                    (isNew, output) = self.writeObjectReference(objRef, output)
                    if isNew:
                        objectsToWrite.append(objRef)
                for objRef in objectsToWrite:
                    output = self.writeObject(objRef, output, setReferencePosition=True)
            elif isinstance(obj, dict):
                output += proc_variable_length(0b1101, len(obj))
                keys = []
                values = []
                objectsToWrite = []
                for key, value in sorted(iteritems(obj)):
                    keys.append(key)
                    values.append(value)
                for key in keys:
                    (isNew, output) = self.writeObjectReference(key, output)
                    if isNew:
                        objectsToWrite.append(key)
                for value in values:
                    (isNew, output) = self.writeObjectReference(value, output)
                    if isNew:
                        objectsToWrite.append(value)
                for objRef in objectsToWrite:
                    output = self.writeObject(objRef, output, setReferencePosition=True)
        return output

Response: Serializes the given object to the output.


Instruction:
Create a Python 3 function for
writing all of the object reference offsets.

Response:
def writeOffsetTable(self, output):
        """Writes all of the object reference offsets."""
        all_positions = []
        writtenReferences = list(self.writtenReferences.items())
        writtenReferences.sort(key=lambda x: x[1])
        for obj,order in writtenReferences:
            # Porting note: Elsewhere we deliberately replace empty unicdoe strings
            # with empty binary strings, but the empty unicode string
            # goes into writtenReferences.  This isn't an issue in Py2
            # because u'' and b'' have the same hash; but it is in
            # Py3, where they don't.
            if bytes != str and obj == unicodeEmpty:
                obj = b''
            position = self.referencePositions.get(obj)
            if position is None:
                raise InvalidPlistException("Error while writing offsets table. Object not found. %s" % obj)
            output += self.binaryInt(position, self.trailer.offsetSize)
            all_positions.append(position)
        return output


Instruction:
Implement a function in Python 3 to
return the number of bytes needed to store the given integer.

Response:
def intSize(self, obj):
        """Returns the number of bytes necessary to store the given integer."""
        # SIGNED
        if obj < 0: # Signed integer, always 8 bytes
            return 8
        # UNSIGNED
        elif obj <= 0xFF: # 1 byte
            return 1
        elif obj <= 0xFFFF: # 2 bytes
            return 2
        elif obj <= 0xFFFFFFFF: # 4 bytes
            return 4
        # SIGNED
        # 0x7FFFFFFFFFFFFFFF is the max.
        elif obj <= 0x7FFFFFFFFFFFFFFF: # 8 bytes signed
            return 8
        elif obj <= 0xffffffffffffffff: # 8 bytes unsigned
            return 16
        else:
            raise InvalidPlistException("Core Foundation can't handle integers with size greater than 8 bytes.")


Instruction:
Create a Python 3 function to
open the z_meso. txt file and return heights as list

Response:
def load_z_meso(self,z_meso_path):
        """ Open the z_meso.txt file and return heights as list """

        self.z_meso = []
        z_meso_file_path = os.path.join(z_meso_path, self.Z_MESO_FILE_NAME)

        # Check if exists
        if not os.path.exists(z_meso_file_path):
            raise Exception("z_meso.txt file: '{}' does not exist.".format(uwg_param_file))

        f = open(z_meso_file_path,'r')
        for txtline in f:
            z_ = float("".join(txtline.split())) # Strip all white spaces and change to float
            self.z_meso.append(z_)
        f.close()


Instruction:
Can you tell what is the following Python 3 function doing
def urbflux(UCM, UBL, BEM, forc, parameter, simTime, RSM):
    T_can = UCM.canTemp
    Cp = parameter.cp
    UCM.Q_roof = 0.
    sigma = 5.67e-8         # Stephan-Boltzman constant
    UCM.roofTemp = 0.       # Average urban roof temperature
    UCM.wallTemp = 0.       # Average urban wall temperature

    for j in range(len(BEM)):
        # Building energy model
        BEM[j].building.BEMCalc(UCM, BEM[j], forc, parameter, simTime)
        BEM[j].ElecTotal = BEM[j].building.ElecTotal * BEM[j].fl_area # W m-2

        # Update roof infra calc
        e_roof = BEM[j].roof.emissivity
        T_roof = BEM[j].roof.layerTemp[0]
        BEM[j].roof.infra = e_roof * (forc.infra - sigma * T_roof**4.)

        # update wall infra calc (road done later)
        e_wall = BEM[j].wall.emissivity
        T_wall = BEM[j].wall.layerTemp[0]
        # calculates the infrared radiation for wall, taking into account radiation exchange from road
        _infra_road_, BEM[j].wall.infra = infracalcs(UCM, forc, UCM.road.emissivity, e_wall, UCM.roadTemp, T_wall)

        # Update element temperatures
        BEM[j].mass.layerTemp = BEM[j].mass.Conduction(simTime.dt, BEM[j].building.fluxMass,1.,0.,BEM[j].building.fluxMass)
        BEM[j].roof.SurfFlux(forc,parameter,simTime,UCM.canHum,T_can,max(forc.wind,UCM.canWind),1.,BEM[j].building.fluxRoof)
        BEM[j].wall.SurfFlux(forc,parameter,simTime,UCM.canHum,T_can,UCM.canWind,1.,BEM[j].building.fluxWall)

        # Note the average wall & roof temperature
        UCM.wallTemp = UCM.wallTemp + BEM[j].frac*BEM[j].wall.layerTemp[0]
        UCM.roofTemp = UCM.roofTemp + BEM[j].frac*BEM[j].roof.layerTemp[0]

    # Update road infra calc (assume walls have similar emissivity, so use the last one)
    UCM.road.infra, _wall_infra = infracalcs(UCM,forc,UCM.road.emissivity,e_wall,UCM.roadTemp,UCM.wallTemp)
    UCM.road.SurfFlux(forc,parameter,simTime,UCM.canHum,T_can,UCM.canWind,2.,0.)
    UCM.roadTemp = UCM.road.layerTemp[0]

    # Sensible & latent heat flux (total)
    if UCM.latHeat != None:
        UCM.latHeat = UCM.latHeat + UCM.latAnthrop + UCM.treeLatHeat + UCM.road.lat*(1.-UCM.bldDensity)

    # ---------------------------------------------------------------------
    # Advective heat flux to UBL from VDM
    #
    # Note: UWG_Matlab code here is modified to compensate for rounding errors
    # that occur when recursively adding forDens, intAdv1, and intAdv2.
    # This causes issues in the UBL.advHeat calculatiuon when large (1e5)
    # numbers are subtracted to produce small numbers (1e-10) that can
    # differ from equivalent matlab calculations by a factor of 2.
    # Values this small are ~ 0, but for consistency's sake Kahan Summation
    # algorithm is applied to keep margin of difference from UWG_Matlab low.
    # ---------------------------------------------------------------------

    forDens = 0.0
    intAdv1 = 0.0
    intAdv2 = 0.0

    # c1 & c2 stores values truncated by floating point rounding for values < 10^-16
    c1 = 0.0
    c2 = 0.0
    c3 = 0.0

    for iz in range(RSM.nzfor):
        # At c loss of precision at at low order of magnitude, that we need in UBL.advHeat calc
        # Algebraically t is 0, but with floating pt numbers c will accumulate truncated values
        y = RSM.densityProfC[iz]*RSM.dz[iz]/(RSM.z[RSM.nzfor-1] + RSM.dz[RSM.nzfor-1]/2.)
        t = forDens + y
        c1 += (t - forDens) - y
        forDens = t

        y = RSM.windProf[iz]*RSM.tempProf[iz]*RSM.dz[iz]
        t = intAdv1 + y
        c2 += (t - intAdv1) - y
        intAdv1 = t

        y = RSM.windProf[iz]*RSM.dz[iz]
        t = intAdv2 + y
        c3 += (t - intAdv2) - y
        intAdv2 = t

    # Add the truncated values back
    forDens -= c1
    intAdv1 -= c2
    intAdv2 -= c3
    UBL.advHeat = UBL.paralLength*Cp*forDens*(intAdv1-(UBL.ublTemp*intAdv2))/UBL.urbArea

    # ---------------------------------------------------------------------
    # Convective heat flux to UBL from UCM (see Appendix - Bueno (2014))
    # ---------------------------------------------------------------------
    zrUrb = 2*UCM.bldHeight
    zref = RSM.z[RSM.nzref-1]    # Reference height

    # Reference wind speed & canyon air density
    windUrb = forc.wind*log(zref/RSM.z0r)/log(parameter.windHeight/RSM.z0r)*\
        log(zrUrb/UCM.z0u)/log(zref/UCM.z0u)
    dens = forc.pres/(1000*0.287042*T_can*(1.+1.607858*UCM.canHum))

    # Friction velocity
    UCM.ustar = parameter.vk*windUrb/log((zrUrb-UCM.l_disp)/UCM.z0u)

    # Convective scaling velocity
    wstar = (parameter.g*max(UCM.sensHeat,0.0)*zref/dens/Cp/T_can)**(1/3.)
    UCM.ustarMod = max(UCM.ustar,wstar)        # Modified friction velocity
    UCM.uExch = parameter.exCoeff*UCM.ustarMod # Exchange velocity

    # Canyon wind speed, Eq. 27 Chp. 3 Hanna and Britter, 2002
    # assuming CD = 1 and lambda_f = verToHor/4
    UCM.canWind = UCM.ustarMod*(UCM.verToHor/8.)**(-1/2.)

    # Canyon turbulent velocities
    UCM.turbU = 2.4*UCM.ustarMod
    UCM.turbV = 1.9*UCM.ustarMod
    UCM.turbW = 1.3*UCM.ustarMod

    # Urban wind profile
    for iz in range(RSM.nzref):
        UCM.windProf.append(UCM.ustar/parameter.vk*\
            log((RSM.z[iz]+UCM.bldHeight-UCM.l_disp)/UCM.z0u))

    return UCM,UBL,BEM

Response: Calculate the surface heat fluxes of the urban and the wall


Instruction:
Write a Python 3 script to
retrieve all the books published by the artist

Response:
def get_books(self):
        """
        Retrieves all the books published by the artist
        :return: List. Books published by the artist
        """
        return itunespy.lookup(id=self.artist_id, entity=itunespy.entities['ebook'])[1:]


Instruction:
Can you create a Python 3 function that
gets a list of tasks optionally filtered by task id.

Response:
def get_tasks(task_id='', completed=True):
    """ Get a list of tasks, optionally filtered by task id.
        The task_id can be the abbrevated.  Example: If a task named 'sleep' is
        scaled to 3 in marathon, there will be be 3 tasks starting with 'sleep.'

        :param task_id: task ID
        :type task_id: str
        :param completed: include completed tasks?
        :type completed: bool

        :return: a list of tasks
        :rtype: []
    """

    client = mesos.DCOSClient()
    master = mesos.Master(client.get_master_state())
    mesos_tasks = master.tasks(completed=completed, fltr=task_id)
    return [task.__dict__['_task'] for task in mesos_tasks]


Instruction:
Make a summary of the following Python 3 code
def get_task(task_id, completed=True):
    tasks = get_tasks(task_id=task_id, completed=completed)

    if len(tasks) == 0:
        return None

    assert len(tasks) == 1, 'get_task should return at max 1 task for a task id'
    return tasks[0]

Response: Get a task by task id where a task_id is required.


Instruction:
Make a summary of the following Python 3 code
def task_completed(task_id):

    tasks = get_tasks(task_id=task_id)
    completed_states = ('TASK_FINISHED',
                        'TASK_FAILED',
                        'TASK_KILLED',
                        'TASK_LOST',
                        'TASK_ERROR')

    for task in tasks:
        if task['state'] in completed_states:
            return True

    return False

Response: Check whether a task has completed.


Instruction:
Here you have a function in Python 3, explain what it does
def task_property_present_predicate(service, task, prop):
    try:
        response = get_service_task(service, task)
    except Exception as e:
        pass

    return (response is not None) and (prop in response)

Response: True if the json_element passed in is present for the task specified.


Instruction:
Write a Python 3 function that can
wait for a task to be launched

Response:
def wait_for_task(service, task, timeout_sec=120):
    """Waits for a task which was launched to be launched"""
    return time_wait(lambda: task_predicate(service, task), timeout_seconds=timeout_sec)


Instruction:
Can you generate the documentation for the following Python 3 function
def wait_for_task_property(service, task, prop, timeout_sec=120):
    return time_wait(lambda: task_property_present_predicate(service, task, prop), timeout_seconds=timeout_sec)

Response: Waits for a task to have the specified property.


Instruction:
Can you generate the documentation for the following Python 3 function
def copy_file(
        host,
        file_path,
        remote_path='.',
        username=None,
        key_path=None,
        action='put'
):
    """ Copy a file via SCP, proxied through the mesos master

        :param host: host or IP of the machine to execute the command on
        :type host: str
        :param file_path: the local path to the file to be copied
        :type file_path: str
        :param remote_path: the remote path to copy the file to
        :type remote_path: str
        :param username: SSH username
        :type username: str
        :param key_path: path to the SSH private key to use for SSH authentication
        :type key_path: str

        :return: True if successful, False otherwise
        :rtype: bool
    """

    if not username:
        username = shakedown.cli.ssh_user

    if not key_path:
        key_path = shakedown.cli.ssh_key_file

    key = validate_key(key_path)

    transport = get_transport(host, username, key)
    transport = start_transport(transport, username, key)

    if transport.is_authenticated():
        start = time.time()

        channel = scp.SCPClient(transport)

        if action == 'get':
            print("\n{}scp {}:{} {}\n".format(shakedown.cli.helpers.fchr('>>'), host, remote_path, file_path))
            channel.get(remote_path, file_path)
        else:
            print("\n{}scp {} {}:{}\n".format(shakedown.cli.helpers.fchr('>>'), file_path, host, remote_path))
            channel.put(file_path, remote_path)

        print("{} bytes copied in {} seconds.".format(str(os.path.getsize(file_path)), str(round(time.time() - start, 2))))

        try_close(channel)
        try_close(transport)

        return True
    else:
        print("error: unable to authenticate {}@{} with key {}".format(username, host, key_path))
        return False

Response: Copy a file via SCP


Instruction:
Given the following Python 3 function, write the documentation
def copy_file_to_master(
        file_path,
        remote_path='.',
        username=None,
        key_path=None
):
    """ Copy a file to the Mesos master
    """

    return copy_file(shakedown.master_ip(), file_path, remote_path, username, key_path)

Response: Copy a file to the master


Instruction:
Given the following Python 3 function, write the documentation
def copy_file_to_agent(
        host,
        file_path,
        remote_path='.',
        username=None,
        key_path=None
):
    """ Copy a file to a Mesos agent, proxied through the master
    """

    return copy_file(host, file_path, remote_path, username, key_path)

Response: Copy a file to a Mesos agent


Instruction:
Explain what the following Python 3 code does
def copy_file_from_master(
        remote_path,
        file_path='.',
        username=None,
        key_path=None
):
    """ Copy a file to the Mesos master
    """

    return copy_file(shakedown.master_ip(), file_path, remote_path, username, key_path, 'get')

Response: Copy a file from the master to the Mesos master


Instruction:
Write a Python 3 function that can
copy a file from a Mesos agent to a master

Response:
def copy_file_from_agent(
        host,
        remote_path,
        file_path='.',
        username=None,
        key_path=None
):
    """ Copy a file to a Mesos agent, proxied through the master
    """

    return copy_file(host, file_path, remote_path, username, key_path, 'get')


Instruction:
Write a Python 3 function for
returning json for specific cluster metadata.

Response:
def __metadata_helper(json_path):
    """ Returns json for specific cluster metadata.  Important to realize that
        this was introduced in dcos-1.9.  Clusters prior to 1.9 and missing metadata
        will return None
    """
    url = shakedown.dcos_url_path('dcos-metadata/{}'.format(json_path))
    try:
        response = dcos.http.request('get', url)

        if response.status_code == 200:
            return response.json()
    except:
        pass

    return None


Instruction:
Write a Python 3 function that can
get the list of resources from the state summary

Response:
def _get_resources(rtype='resources'):
    """ resource types from state summary include:  resources, used_resources
    offered_resources, reserved_resources, unreserved_resources
    The default is resources.

    :param rtype: the type of resources to return
    :type rtype: str
    :param role: the name of the role if for reserved and if None all reserved
    :type rtype: str

    :return: resources(cpu,mem)
    :rtype: Resources
    """
    cpus = 0
    mem = 0
    summary = DCOSClient().get_state_summary()

    if 'slaves' in summary:
        agents = summary.get('slaves')
        for agent in agents:
            if agent[rtype].get('cpus') is not None:
                cpus += agent[rtype].get('cpus')
            if agent[rtype].get('mem') is not None:
                mem += agent[rtype].get('mem')

    return Resources(cpus, mem)


Instruction:
Create a Python 3 function for
returning the number of resources that are reserved and are reserved and the same as the current state

Response:
def get_reserved_resources(role=None):
    """ resource types from state summary include: reserved_resources

    :param role: the name of the role if for reserved and if None all reserved
    :type role: str

    :return: resources(cpu,mem)
    :rtype: Resources
    """
    rtype = 'reserved_resources'
    cpus = 0.0
    mem = 0.0
    summary = DCOSClient().get_state_summary()

    if 'slaves' in summary:
        agents = summary.get('slaves')
        for agent in agents:
            resource_reservations = agent.get(rtype)
            reservations = []
            if role is None or '*' in role:
                reservations = resource_reservations.values()
            elif role in resource_reservations:
                reservations = [resource_reservations.get(role)]
            for reservation in reservations:
                if reservation.get('cpus') is not None:
                    cpus += reservation.get('cpus')
                if reservation.get('mem') is not None:
                    mem += reservation.get('mem')

    return Resources(cpus, mem)


Instruction:
Given the following Python 3 function, write the documentation
def log_decl_method(func):
    from functools import wraps

    @wraps(func)
    def with_logging(*args, **kwargs):
        self = args[0]
        decl = args[2]
        log(DEBUG, u"    {}: {} {}".format(
            self.state['current_step'], decl.name,
            serialize(decl.value).strip()).encode('utf-8'))
        return func(*args, **kwargs)
    return with_logging

Response: Decorate do_declartion methods for debug logging.


Instruction:
Implement a Python 3 function for
converting a css selector to an xpath supporting pseudo elements.

Response:
def css_to_func(css, flags, css_namespaces, lang):
    """Convert a css selector to an xpath, supporting pseudo elements."""
    from cssselect import parse, HTMLTranslator
    from cssselect.parser import FunctionalPseudoElement
    #  FIXME HACK need lessc to support functional-pseudo-selectors instead
    #  of marking as strings and stripping " here.
    if not (css):
        return None

    sel = parse(css.strip('" '))[0]
    xpath = HTMLTranslator().selector_to_xpath(sel)

    first_letter = False
    if sel.pseudo_element is not None:
        if type(sel.pseudo_element) == FunctionalPseudoElement:
            if sel.pseudo_element.name in ('attr', 'first-letter'):
                xpath += '/@' + sel.pseudo_element.arguments[0].value
                if sel.pseudo_element.name == 'first-letter':
                    first_letter = True
        elif isinstance(sel.pseudo_element, type(u'')):
            if sel.pseudo_element == 'first-letter':
                first_letter = True

    xp = etree.XPath(xpath, namespaces=css_namespaces)

    def toupper(u):
        """Use icu library for locale sensitive uppercasing (python2)."""
        loc = Locale(lang) if lang else Locale()
        return UnicodeString(u).toUpper(loc).encode('utf-8').decode('utf-8')

    def func(elem):
        res = xp(elem)
        if res:
            if etree.iselement(res[0]):
                res_str = etree.tostring(res[0], encoding='unicode',
                                         method="text")
            else:
                res_str = res[0]
            if first_letter:
                if res_str:
                    if flags and 'nocase' in flags:
                        return toupper(res_str[0])
                    else:
                        return res_str[0]
                else:
                    return res_str
            else:
                if flags and 'nocase' in flags:
                    return toupper(res_str)
                else:
                    return res_str

    return func


Instruction:
Make a summary of the following Python 3 code
def append_string(t, string):
    node = t.tree
    if string:
        if len(node) == 0:
            if node.text is not None:
                node.text += string
            else:
                node.text = string
        else:  # Get last child
            child = list(node)[-1]
            if child.tail is not None:
                child.tail += string
            else:
                child.tail = string

Response: Append a string to a node as text or tail of last child.


Instruction:
Can you implement a function in Python 3 that
inserts value into the target tree t with correct grouping.

Response:
def grouped_insert(t, value):
    """Insert value into the target tree 't' with correct grouping."""
    collator = Collator.createInstance(Locale(t.lang) if t.lang else Locale())
    if value.tail is not None:
        val_prev = value.getprevious()
        if val_prev is not None:
            val_prev.tail = (val_prev.tail or '') + value.tail
        else:
            val_parent = value.getparent()
            if val_parent is not None:
                val_parent.text = (val_parent.text or '') + value.tail
        value.tail = None
    if t.isgroup and t.sort(value) is not None:
        if t.groupby:
            for child in t.tree:
                if child.get('class') == 'group-by':
                    # child[0] is the label span
                    order = collator.compare(
                        t.groupby(child[1]) or '', t.groupby(value) or '')
                    if order == 0:
                        c_target = Target(child, sort=t.sort, lang=t.lang)
                        insert_group(value, c_target)
                        break
                    elif order > 0:
                        group = create_group(t.groupby(value))
                        group.append(value)
                        child.addprevious(group)
                        break
            else:
                group = create_group(t.groupby(value))
                group.append(value)
                t.tree.append(group)
        else:
            insert_group(value, t)

    elif t.sort and t.sort(value) is not None:
        insert_sort(value, t)

    elif t.location == 'inside':
        for child in t.tree:
            value.append(child)
        value.text = t.tree.text
        t.tree.text = None
        t.tree.append(value)

    elif t.location == 'outside':
        value.tail = t.tree.tail
        t.tree.tail = None
        target_parent_descendants = (
            [n.getparent() for n in t.parent.iterdescendants() if n == t.tree])
        try:
            parent = target_parent_descendants[0]
            parent.insert(parent.index(t.tree), value)
            value.append(t.tree)
        except IndexError as e:
            logger.error('Target of outside has been moved or deleted')
            raise e

    elif t.location == 'before':
        value.tail = t.tree.text
        t.tree.text = None
        t.tree.insert(0, value)
    else:
        t.tree.append(value)


Instruction:
Make a summary of the following Python 3 code
def insert_sort(node, target):
    sort = target.sort
    lang = target.lang
    collator = Collator.createInstance(Locale(lang) if lang else Locale())
    for child in target.tree:
        if collator.compare(sort(child) or '', sort(node) or '') > 0:
            child.addprevious(node)
            break
    else:
        target.tree.append(node)

Response: Insert node into sorted position in target tree.


Instruction:
Write a Python 3 script for
inserting node into target tree in appropriate group.

Response:
def insert_group(node, target):
    """Insert node into in target tree, in appropriate group.

    Uses group and lang from target function.  This assumes the node and
    target share a structure of a first child that determines the grouping,
    and a second child that will be accumulated in the group.
    """
    group = target.sort
    lang = target.lang

    collator = Collator.createInstance(Locale(lang) if lang else Locale())
    for child in target.tree:
        order = collator.compare(group(child) or '', group(node) or '')
        if order == 0:
            for nodechild in node[1:]:
                child.append(nodechild)
            break
        elif order > 0:
            child.addprevious(node)
            break
    else:
        target.tree.append(node)


Instruction:
Write a Python 3 script for
creating the group wrapper node.

Response:
def create_group(value):
    """Create the group wrapper node."""
    node = etree.Element('div', attrib={'class': 'group-by'})
    span = etree.Element('span', attrib={'class': 'group-label'})
    span.text = value
    node.append(span)
    return node


Instruction:
How would you code a function in Python 3 to
return selector special pseudo class info.

Response:
def extract_selector_info(sel):
    """Return selector special pseudo class info (steps and other)."""
    #  walk the parsed_tree, looking for pseudoClass selectors, check names
    # add in steps and/or deferred extras
    steps, extras = _extract_sel_info(sel.parsed_tree)
    steps = sorted(set(steps))
    extras = sorted(set(extras))
    if len(steps) == 0:
        steps = ['default']
    return (steps, extras)


Instruction:
Can you tell what is the following Python 3 function doing
def _to_roman(num):
    roman_numeral_map = (
        ('M',  1000),
        ('CM', 900),
        ('D',  500),
        ('CD', 400),
        ('C',  100),
        ('XC', 90),
        ('L',  50),
        ('XL', 40),
        ('X',  10),
        ('IX', 9),
        ('V',  5),
        ('IV', 4),
        ('I',  1)
    )
    if not (0 < num < 5000):
        log(WARN, 'Number out of range for roman (must be 1..4999)')
        return str(num)
    result = ''
    for numeral, integer in roman_numeral_map:
        while num >= integer:
            result += numeral
            num -= integer
    return result

Response: Convert integer to roman numerals.


Instruction:
Create a Python 3 function for
making a deep copy of the provided tree with the provided id suffix.

Response:
def copy_w_id_suffix(elem, suffix="_copy"):
    """Make a deep copy of the provided tree, altering ids."""
    mycopy = deepcopy(elem)
    for id_elem in mycopy.xpath('//*[@id]'):
        id_elem.set('id', id_elem.get('id') + suffix)
    return mycopy


Instruction:
Here you have a function in Python 3, explain what it does
def generate_id(self):
        if self.use_repeatable_ids:
            self.repeatable_id_counter += 1
            return 'autobaked-{}'.format(self.repeatable_id_counter)
        else:
            return str(uuid4())

Response: Generate a fresh id


Instruction:
Implement a function in Python 3 to
clear the recipe state.

Response:
def clear_state(self):
        """Clear the recipe state."""
        self.state = {}
        self.state['steps'] = []
        self.state['current_step'] = None
        self.state['scope'] = []
        self.state['counters'] = {}
        self.state['strings'] = {}
        for step in self.matchers:
            self.state[step] = {}
            self.state[step]['pending'] = {}
            self.state[step]['actions'] = []
            self.state[step]['counters'] = {}
            self.state[step]['strings'] = {}
            # FIXME rather than boolean should ref HTML tree
            self.state[step]['recipe'] = False


Instruction:
Can you write a function in Python 3 where it
updates the internal state of the internal state with the CSS rules in css_in.

Response:
def update_css(self, css_in=None, clear_css=False):
        """Add additional CSS rules, optionally replacing all."""
        if clear_css:
            self.matchers = {}

        # CSS is changing, so clear processing state
        self.clear_state()

        if css_in is None:
            return
        try:
            with open(css_in, 'rb') as f:  # is it a path/filename?
                css = f.read()
        except (IOError, TypeError):
            try:
                css = css_in.read()  # Perhaps a file obj?
            except AttributeError:
                css = css_in         # Treat it as a string

        # Namespaces defined in the CSS
        if clear_css:
            self.css_namespaces = {}

        rules, _ = tinycss2.parse_stylesheet_bytes(css, skip_whitespace=True)
        for rule in rules:
            # Check for any @namespace declarations
            if rule.type == 'at-rule':
                if rule.lower_at_keyword == 'namespace':
                    # The 1 supported format is:
                    #
                    # default (unsupported):  [<WhitespaceToken>,
                    #            <StringToken "http://www.w3.org/1999/xhtml">]
                    # prefixed: [<WhitespaceToken>,
                    #            <IdentToken html>,
                    #            <WhitespaceToken>,
                    #            <StringToken "http://www.w3.org/1999/xhtml">]
                    if len(rule.prelude) == 4 and \
                           [tok.type for tok in rule.prelude] == \
                           ['whitespace', 'ident', 'whitespace', 'string']:

                        # Prefixed namespace
                        ns_prefix = rule.prelude[1].value
                        ns_url = rule.prelude[3].value
                        self.css_namespaces[ns_prefix] = ns_url
                    else:
                        # etree.XPath does not support the default namespace
                        # and XPath is used to implement `sort-by:`
                        # http://www.goodmami.org/2015/11/04/
                        # ... python-xpath-and-default-namespaces.html
                        log(WARN, u'Unknown @namespace format at {}:{}'
                            .format(rule.source_line, rule.source_column)
                            .encode('utf-8'))

            elif rule.type == 'qualified-rule':

                selectors = parse(rule.prelude, namespaces=self.css_namespaces,
                                  extensions=extensions)
                decls = [d for d in
                         parse_declaration_list(rule.content,
                                                skip_whitespace=True)
                         if d.type == 'declaration']  # Could also be a comment
                for sel in selectors:
                    try:
                        csel = CompiledSelector(sel)
                    except cssselect2.SelectorError as error:
                        log(WARN, u'Invalid selector: {} {}'.format(
                            serialize(rule.prelude),
                            to_str(error.args)).encode('utf-8'))
                    else:
                        steps, extras = extract_selector_info(sel)
                        label = csel.pseudo_element
                        if len(extras) > 0:
                            if label is not None:
                                extras.insert(0, label)
                            label = '_'.join(extras)

                        for step in steps:
                            if step not in self.matchers:
                                self.matchers[step] = cssselect2.Matcher()
                            self.record_coverage_zero(rule,
                                                      sel.source_line_offset)
                            self.matchers[step].add_selector(
                                 csel,
                                 ((rule.source_line + sel.source_line_offset,
                                   serialize(rule.prelude).replace('\n', ' ')),
                                  decls, label))
            elif rule.type == 'comment':
                pass
            elif rule.type == 'error':
                log(ERROR, u'Parse Error {}: {}'.format(
                    rule.kind, rule.message).encode('utf-8'))
                # Phil does not know how to nicely exit with staus != 0
                raise ValueError(u'Parse Error {}: {}'.format(
                    rule.kind, rule.message).encode('utf-8'))
            else:
                raise ValueError(u'BUG: Unknown ruletype={}'.format(rule.type))

        steps = sorted(self.matchers.keys())
        if len(steps) > 1:
            if 'default' in steps:
                steps.remove('default')
                try:
                    steps.sort(key=int)
                    steps.insert(0, '0')
                    self.matchers['0'] = self.matchers.pop('default')
                except ValueError:
                    steps.insert(0, 'default')
            else:
                try:
                    steps.sort(key=int)
                except ValueError:
                    pass  # already sorted alpha

        self.clear_state()
        self.state['steps'] = steps
        log(DEBUG, 'Passes: {}'.format(to_str(steps)))


Instruction:
Implement a function in Python 3 to
apply recipes to HTML tree. Will build recipes if needed.

Response:
def bake(self, element, last_step=None):
        """Apply recipes to HTML tree. Will build recipes if needed."""

        if last_step is not None:
            try:
                self.state['steps'] = [s for s in self.state['steps']
                                       if int(s) < int(last_step)]
            except ValueError:
                self.state['steps'] = [s for s in self.state['steps']
                                       if s < last_step]
        for step in self.state['steps']:
            self.state['current_step'] = step
            self.state['scope'].insert(0, step)
            # Need to wrap each loop, since tree may have changed
            wrapped_html_tree = ElementWrapper.from_html_root(element)

            if not self.state[step]['recipe']:
                recipe = self.build_recipe(wrapped_html_tree, step)
            else:
                recipe = self.state[step]

            log(DEBUG, u'Recipe {} length: {}'.format(
                step, len(recipe['actions'])).encode('utf-8'))
            target = None
            old_content = {}
            node_counts = {}
            for action, value in recipe['actions']:
                if action == 'target':
                    target = value
                    old_content = {}
                elif action == 'tag':
                    target.tree.tag = value
                elif action == 'clear':
                    old_content['text'] = target.tree.text
                    target.tree.text = None
                    old_content['children'] = []
                    for child in target.tree:
                        old_content['children'].append(child)
                        target.tree.remove(child)
                elif action == 'content':
                    if value is not None:
                        append_string(target, value.text)
                        for child in value:
                            target.tree.append(child)
                    elif old_content:
                        append_string(target, old_content['text'])
                        for child in old_content['children']:
                            target.tree.append(child)
                elif action == 'attrib':
                    attname, vals = value
                    strval = u''.join([u'{}'.format(s) for s in vals])
                    target.tree.set(attname, strval)
                elif action == 'string':
                    strval = u''.join([u'{}'.format(s) for s in value])
                    if target.location == 'before':
                        prepend_string(target, strval)
                    else:
                        append_string(target, strval)
                elif action == 'move':
                    grouped_insert(target, value)
                elif action == 'copy':
                    mycopy = copy_w_id_suffix(value)
                    mycopy.tail = None
                    grouped_insert(target, mycopy)
                elif action == 'nodeset':
                    node_counts[value] = node_counts.setdefault(value, 0) + 1
                    suffix = u'_copy_{}'.format(node_counts[value])
                    mycopy = copy_w_id_suffix(value, suffix)
                    mycopy.tail = None
                    grouped_insert(target, mycopy)
                else:
                    log(WARN, u'Missing action {}'.format(
                        action).encode('utf-8'))

        # Do numbering

        # Do label/link updates

        # Add an empty string to each element just to make sure the element
        # is closed. This is useful for browsers that parse the output
        # as HTML5 rather than as XHTML5.
        #
        # One use-case would be users that inject the content into an
        # existing HTML (not XHTML) document.
        walkAll = element.iter()
        for elt in walkAll:
            if elt.tag not in SELF_CLOSING_TAGS:
                if len(elt) == 0 and not elt.text:
                    elt.text = ''


Instruction:
Here you have a function in Python 3, explain what it does
def record_coverage_zero(self, rule, offset):
        self.coverage_lines.append('DA:{},0'.format(rule.source_line + offset))

Response: Add entry to coverage_lines if this selector was parsed


Instruction:
Create a Python 3 function to
add entry to coverage saying this selector was matched

Response:
def record_coverage(self, rule):
        """Add entry to coverage saying this selector was matched"""
        log(DEBUG, u'Rule ({}): {}'.format(*rule).encode('utf-8'))
        self.coverage_lines.append('DA:{},1'.format(rule[0]))


Instruction:
Can you tell what is the following Python 3 function doing
def build_recipe(self, element, step, depth=0):
        element_id = element.etree_element.get('id')

        self.state['lang'] = element.lang

        matching_rules = {}
        #  specificity, order, pseudo, payload = match
        #  selector_rule, declaration_list, label = payload
        for _, _, pseudo, payload in self.matchers[step].match(element):
            rule, decs, label = payload
            matching_rules.setdefault(label, []).append((rule, decs))

        # Do non-pseudo
        if None in matching_rules:
            for rule, declarations in matching_rules.get(None):
                self.record_coverage(rule)
                self.push_target_elem(element)
                for decl in declarations:
                    method = self.find_method(decl)
                    method(element, decl, None)

        # Store all variables (strings and counters) before children
        if element_id:
            temp_counters = {}
            temp_strings = {}
            for s_step in self.state['scope']:
                temp_counters[s_step] = {
                        'counters': deepcopy(self.state[s_step]['counters'])}
                temp_strings[s_step] = {
                        'strings': deepcopy(self.state[s_step]['strings'])}

            self.state['counters'][element_id] = temp_counters
            self.state['strings'][element_id] = temp_strings

        # Do before
        if 'before' in matching_rules:
            for rule, declarations in matching_rules.get('before'):
                self.record_coverage(rule)
                # pseudo element, create wrapper
                self.push_pending_elem(element, 'before')
                for decl in declarations:
                    method = self.find_method(decl)
                    method(element, decl, 'before')
                # deal w/ pending_elements, per rule
                self.pop_pending_if_empty(element)

        # Recurse
        for el in element.iter_children():
            _state = self.build_recipe(el, step, depth=depth+1)  # noqa

        # Do after
        if 'after' in matching_rules:
            for rule, declarations in matching_rules.get('after'):
                self.record_coverage(rule)
                # pseudo element, create wrapper
                self.push_pending_elem(element, 'after')
                for decl in declarations:
                    method = self.find_method(decl)
                    method(element, decl, 'after')
                # deal w/ pending_elements, per rule
                self.pop_pending_if_empty(element)

        # Do outside
        if 'outside' in matching_rules:
            for rule, declarations in matching_rules.get('outside'):
                self.record_coverage(rule)
                self.push_pending_elem(element, 'outside')
                for decl in declarations:
                    method = self.find_method(decl)
                    method(element, decl, 'outside')

        # Do inside
        if 'inside' in matching_rules:
            for rule, declarations in matching_rules.get('inside'):
                self.record_coverage(rule)
                self.push_pending_elem(element, 'inside')
                for decl in declarations:
                    method = self.find_method(decl)
                    method(element, decl, 'inside')

        # Do deferred
        if ('deferred' in matching_rules or
             'after_deferred' in matching_rules or  # NOQA
             'before_deferred' in matching_rules or
             'outside_deferred' in matching_rules or
             'inside_deferred' in matching_rules):

            # store strings and counters, in case a deferred rule changes one
            if element_id:
                temp_counters = {}
                temp_strings = {}
                for s_step in self.state['scope']:
                    temp_counters[s_step] = {
                        'counters': deepcopy(self.state[s_step]['counters'])}
                    temp_strings[s_step] = {
                        'strings': deepcopy(self.state[s_step]['strings'])}

            # Do straight up deferred
            if 'deferred' in matching_rules:
                for rule, declarations in matching_rules.get('deferred'):
                    self.record_coverage(rule)
                    self.push_target_elem(element)
                    for decl in declarations:
                        method = self.find_method(decl)
                        method(element, decl, None)

            # Do before_deferred
            if 'before_deferred' in matching_rules:
                for rule, declarations in \
                        matching_rules.get('before_deferred'):
                    self.record_coverage(rule)
                    # pseudo element, create wrapper
                    self.push_pending_elem(element, 'before')
                    for decl in declarations:
                        method = self.find_method(decl)
                        method(element, decl, 'before')
                    # deal w/ pending_elements, per rule
                    self.pop_pending_if_empty(element)

            # Do after_deferred
            if 'after_deferred' in matching_rules:
                for rule, declarations in matching_rules.get('after_deferred'):
                    self.record_coverage(rule)
                    # pseudo element, create wrapper
                    self.push_pending_elem(element, 'after')
                    for decl in declarations:
                        method = self.find_method(decl)
                        method(element, decl, 'after')
                    # deal w/ pending_elements, per rule
                    self.pop_pending_if_empty(element)

            # Do outside_deferred
            if 'outside_deferred' in matching_rules:
                for rule, declarations in \
                        matching_rules.get('outside_deferred'):
                    self.record_coverage(rule)
                    self.push_pending_elem(element, 'outside')
                    for decl in declarations:
                        method = self.find_method(decl)
                        method(element, decl, 'outside')

            # Do inside_deferred
            if 'inside_deferred' in matching_rules:
                for rule, declarations in \
                        matching_rules.get('inside_deferred'):
                    self.record_coverage(rule)
                    self.push_pending_elem(element, 'inside')
                    for decl in declarations:
                        method = self.find_method(decl)
                        method(element, decl, 'inside')

            # Did a deferred rule change a stored variable?
            if element_id:
                for s_step in self.state['scope']:
                    for counter, val in self.state[s_step]['counters'].items():
                        if (counter not in temp_counters or
                                temp_counters[counter] != val):
                            self.state['counters'][element_id][s_step]['counters'][counter] = val  # NOQA
                    for string, val in self.state[s_step]['strings'].items():
                        if (string not in temp_strings or
                                temp_strings[string] != val):
                            self.state['strings'][element_id][s_step]['strings'][string] = val  # NOQA

        if depth == 0:
            self.state[step]['recipe'] = True  # FIXME should ref HTML tree
        return self.state[step]

Response: Build a set of steps to collate an HTML doc.


Instruction:
How would you explain what the following Python 3 function does
def push_target_elem(self, element, pseudo=None):
        actions = self.state[self.state['current_step']]['actions']
        if len(actions) > 0 and actions[-1][0] == 'target':
            actions.pop()
        actions.append(('target', Target(element.etree_element,
                                         pseudo, element.parent.etree_element
                                         )))

Response: Place target element onto action stack.


Instruction:
Here you have a function in Python 3, explain what it does
def push_pending_elem(self, element, pseudo):
        self.push_target_elem(element, pseudo)
        elem = etree.Element('div')
        actions = self.state[self.state['current_step']]['actions']
        actions.append(('move', elem))
        actions.append(('target', Target(elem)))

Response: Create and place pending target element onto stack.


Instruction:
Make a summary of the following Python 3 code
def pop_pending_if_empty(self, element):
        actions = self.state[self.state['current_step']]['actions']
        elem = self.current_target().tree
        if actions[-1][0] == ('target') and actions[-1][1].tree == elem:
            actions.pop()
            actions.pop()
            actions.pop()

Response: Remove empty wrapper element.


Instruction:
Write a Python 3 script to
find method to call for declaration based on name.

Response:
def find_method(self, decl):
        """Find class method to call for declaration based on name."""
        name = decl.name
        method = None
        try:
            method = getattr(self, u'do_{}'.format(
                             (name).replace('-', '_')))
        except AttributeError:
            if name.startswith('data-'):
                method = getattr(self, 'do_data_any')
            elif name.startswith('attr-'):
                method = getattr(self, 'do_attr_any')
            else:
                log(WARN, u'Missing method {}'.format(
                                 (name).replace('-', '_')).encode('utf-8'))
        if method:
            self.record_coverage_line(decl.source_line)
            return method
        else:
            return lambda x, y, z: None